arkgate 3.0.5 → 3.2.0

package/docs/agent-guide.md

@@ -3,7 +3,9 @@
 **ArkGate** (`arkgate`) — architecture co-pilot for AI TypeScript. This guide describes how AI
 agents and codegen tools safely interact with write hooks, advisory MCP tools, CI, and `/ark-*`
 skills. Guarantees differ by host; start with the
-[canonical host support matrix](../README.md#host-enforcement-support).
+[canonical host support matrix](../README.md#host-enforcement-support). The advisory-local /
+hard-CI split is a deliberate trade-off, not a gap: local hooks and MCP coach at write time,
+while a required merge status is the one boundary a repository can make every write path share.
 
 CLI names: prefer **`arkgate` / `arkgate-check` / `arkgate-mcp`**; aliases `ark` / `ark-check` /
 `ark-mcp` still work for one major. TypeScript **5.x / 6.x / 7.x** as the project compiler:
@@ -57,7 +59,8 @@ MCP `ark_recommend` and the `/ark-architect` skill.
 ### Terminal onboarding (Phase B)
 
 ```bash
-npx ark start --yes                             # preferred: shape → compact contract → active host → CI → plan
+npx ark start --yes                           # preferred read-only preview: shape → contract → host → CI
+npx ark start --yes --apply                   # apply exactly the previewed compact setup
 npx ark init --archetype crud-product --yes   # non-interactive: shape → preset → origin → gates
 npx ark init                                    # TTY wizard: pick application shape (1–8), not a framework
 npx ark-check --doctor                          # includes "New here?" when coverage is low or config is fresh
@@ -66,8 +69,8 @@ npx ark-check --watch                           # debounced re-check when govern
 ```
 
 **Day-zero origin (2.12+):** `ark init` freezes `.ark/reports/origin.*` before writing agent
-docs or CI templates. Compact `ark start` keeps first-run setup under five project files and
-25 KB;
+docs or CI templates. Compact `ark start` previews first and keeps the applied setup under five
+project files and 25 KB;
 run `ark-check --report ark-report.html` explicitly when you want to establish an origin/evolution
 baseline. Do not `--reset-origin` unless the user explicitly wants a new baseline.
 
@@ -116,6 +119,23 @@ Smell **ids** (stable JSON) plus **outcome** lines (plain language, Q02) on each
 | `mixed-pattern-cluster` | Several layout styles — pick one golden pattern + pilot |
 | `soft-contract` | Layers without deny rules — add real walls, not soft green |
 
+**Contract health (W01):** doctor JSON also carries `contractHealth` — a meta-lint of the
+contract itself (never of the code): `contract-bidirectional-allow` (both directions explicitly
+allowed between two layers), `contract-peripheral-depends-core` (audit/observability layer allowed
+into orchestration/persistence), `contract-lateral-adapter-allow` (adapter layer allowed into a
+sibling adapter layer), `contract-dead-rule` (rule references an empty or unknown layer, or is a
+same-layer no-op; `optional: true` layers are exempt). Advisory only: it never changes the
+verdict, `designFitness`, or `patternBets` — layer roles come from name heuristics, so treat a
+miss as a warning to read, not a defect to silence. A deliberate edge is acknowledged in
+`.ark/contract-smell-acks.json` (`{ acks: [{ id, edge, reason }] }`); `acknowledged` counts
+applied acks only, and a malformed sidecar or edge string suppresses nothing.
+
+**Governance weight (W02):** `contractHealth.governanceWeight` reports raw facts (layers, rules,
+governed files, files/layer, rules/layer) plus a fixed band (`heavy` / `typical` / `light` /
+`unknown`) with fixed wording. It is explicitly `notAScore` — never a gate input. Read `heavy` as
+"justify the next layer/rule with demonstrated pressure", never as "delete layers"; read `light`
+as "a boundary may be missing where violations concentrate".
+
 Each smell also has `evidence[]` paths and `message` (technical detail). Plan **B** bets include
 `pilot`, `successSignal`, `killSwitch`, and **`neverMechanicalSafe: true`** — loop/autoPatch must
 ignore them. For judgment I/O moves use **extraction cards**
@@ -281,14 +301,21 @@ Prefer preparing the write before the host commits it to disk:
 | Surface | Role |
 |---------|------|
 | MCP **`ark_prepare_write`** | Place + constrain + validate + optional `autoPatch` + `judgmentBrief` + contentHash + optional `goldenPattern` in one call |
+| MCP **`ark_prepare_change`** | Validate one complete create/update/delete batch in memory; optional `changeMap` also returns structural convergence; never writes |
+| CLI **`ark preflight --changes <file> --json`** | Same atomic verdict and map convergence for hosts/scripts that do not call MCP |
 | 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 |
+| Doctor **`writePath`** | Reports installed mode plus `enforcementLadder` (`supported` / `installed` / `active` / `bypassable`, evidence, operation coverage, required-status honesty) |
 | Doctor **`goldenPattern`** | Optional Q03 advisory summary (`present` / `invalid`); never clears design-weak |
 
 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`.
 
+Blocking diagnostics carry one deterministic `nextAction` in both human and JSON output. Complete
+Codex `ApplyPatch` payloads use the same atomic batch engine as CLI/MCP before single-file safety
+checks; this improves early feedback without upgrading Codex's bypassable hook to a universal hard
+boundary. Removing `AGENTS.md`, skills, or session context never changes the contract verdict.
+
 Do not invent layers outside the 11-layer profile or named presets. Unrecognized
 directories (`utils/`, `lib/`) must be classified explicitly via `/ark-contract`.
 
@@ -672,6 +699,13 @@ The strongest place to constrain an AI agent is the moment it writes a file, not
 JS-API TypeScript — nested or project) so a host can gate
 the write path:
 
+For a complete multi-file candidate, use `ark preflight --changes changes.json --json` or MCP
+`ark_prepare_change`. Add `--change-map map.json` (or MCP `changeMap`) only for an explicit schema
+`1.0` structural plan. Ark binds its normalized `changeMapHash` and compares the full candidate
+against the current supplied base. `convergence.findings` separates satisfied, missing,
+contradictory, and unplanned paths/edges; any structural mismatch rejects the batch. No map is
+required, and `behavioralCompletion` remains `not-evaluated` even when structure converges.
+
 ```bash
 npx ark-mcp --root . --config ark.config.json [--manifest ark.manifest.json]
 ```

package/docs/ai-gates.md

@@ -5,34 +5,29 @@ On Claude Code and Grok Build, an installed and trusted PreToolUse hook can bloc
 before they land on disk. Cursor and OpenAI Codex use advisory MCP validation at write time; CI is
 their hard repository check. Codex 0.123+ dispatches hooks for its native `apply_patch` handler,
 but Code Mode hosts can execute deferred nested writes without that project hook event. See the
-[canonical host support matrix](../README.md#host-enforcement-support) before installing.
+[canonical host support matrix](../README.md#host-enforcement-support) before installing. The
+advisory-local / hard-CI split is a deliberate trade-off: local surfaces optimize feedback speed,
+while a required merge status is the one boundary a repository can make every write path share.
 
 Everything below uses the same `ark.config.json` as `arkgate-check` / `ark-check` (CI) — one
 contract shared by every surface. Generate it once:
 
 ```bash
 npx arkgate-check --init
-# aliases: ark-check, ark init, arkgate start
+# aliases: ark-check --init, ark init
 ```
 
 For guided setup with prompts, use:
 
 ```bash
-npx arkgate start
+npx arkgate start          # read-only preview
+npx arkgate start --apply  # apply exactly the previewed setup
 # or: npx ark init
 ```
 
-`ark start` asks for the active agent on a TTY (or detects it otherwise) and applies a compact
-router setup: at most five project files and no `package.json` change unless you pass `--install`.
-Use `--tools <host>` to select the host explicitly. The broader command below remains the explicit
-way to install the full per-host `/ark-*` skill inventory.
-
-For non-interactive defaults, use:
-
-```bash
-npx arkgate start --yes
-# or: npx ark init --yes
-```
+`ark start` detects one active host and previews a compact setup (≤5 files / 25 KB). Nothing is
+written until `--apply`, which rejects stale inputs. Select a host with `--tools <host>`; use the
+broader installer below only for the full `/ark-*` inventory.
 
 You can also generate only the starter gate files for common agent runtimes and CI:
 
@@ -48,7 +43,11 @@ you pass `--force`, so review and commit only the templates that match your proj
 **Doctor (W5):** `ark-check --doctor --json` includes `doctor.writePath`
 (`mode`: `repair` | `reject-only` | `mcp-only` | `none`, plus `prepareWrite` /
 `autoPatch` flags), the supported profile for the active host, and the evidence actually found.
-Supported capability and installed guarantee are deliberately separate.
+`writePath.enforcementLadder` separates `supported`, `installed`, `active`, and `bypassable` for
+local hooks, advisory MCP, and CI. Doctor leaves hook trust and required-status policy
+`unverified`; an actual covered PreToolUse denial can report operation-scoped activity. Codex
+`apply_patch` can expose a complete patch to the shared atomic preflight, but the host remains
+bypassable/advisory because some Code Mode paths do not dispatch the project hook.
 
 **Design fitness (3.0.1+):** the same doctor JSON may include `doctor.designFitness` and
 `doctor.designSmells[]` (path evidence). Edge-clean `operatingMode: enforce` can still set
@@ -182,6 +181,9 @@ The MCP server exposes a resource and tools agents can use proactively (not an e
 - **`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). 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_prepare_change`** (tool) — **T02–T05:** read-only atomic create/update/delete preflight with cross-file edge/cycle findings and candidate fingerprints. Optional `changeMap` accepts strict schema `1.0` intent and returns its hash plus satisfied/missing/contradictory/unplanned structural convergence; behavioral completion is not evaluated. Omission is supported. MCP registration remains advisory unless the host makes invocation non-bypassable.
+- Blocking CLI/MCP/hook diagnostics include the same deterministic `nextAction`. `AGENTS.md`, skill
+  catalogs, session prose, and live LLM calls are not inputs to the enforcement verdict.
 - **`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/configuration.md

@@ -95,3 +95,47 @@ Safety fields:
 
 The packaged JSON Schema is authoritative for types, constraints, defaults, and the unknown-key
 policy.
+
+## Contract transitions
+
+`ark-check --strict-merge` protects the transition into a new contract, not only the resulting
+file. In a Git checkout it compares the candidate `ark.config.json` with the merge base when that
+base is available. CI can bind the comparison explicitly:
+
+```bash
+ARK_POLICY_BASE_REF="$BASE_SHA" npx ark-check --strict-merge
+```
+
+For local or non-Git automation, supply a committed config file or Git ref:
+
+```bash
+npx ark-check --strict-config --policy-base ./before.ark.config.json --json
+npx ark-check --strict-merge --policy-base-ref origin/main
+```
+
+The additive JSON result includes `policyDelta`: both policy hashes, the overall classification,
+stable findings, and `blockingFindingIds`. Supported comparisons cover governed include/exclude
+roots, layer patterns/exclusions/forbidden globals, deny rules, same-layer peer isolation,
+cycle policy, dynamic-import allowlists, and safety thresholds. Ambiguous ownership changes are
+`judgment-required` rather than guessed.
+
+Weakening and judgment-required transitions fail closed. An intentional exception is an explicit
+JSON artifact passed with `--policy-ack`:
+
+```json
+{
+  "schemaVersion": "1.0",
+  "basePolicyHash": "fnv1a-...",
+  "candidatePolicyHash": "fnv1a-...",
+  "findingIds": ["weakening:$.dynamicImportAllowlist:added"],
+  "reason": "Temporary loader while the static registry is migrated."
+}
+```
+
+The acknowledgement must list every blocking finding exactly. It is not a permanent allowlist:
+changing either contract changes its hash and invalidates the acknowledgement.
+
+MCP clients can call `ark_policy_delta` with the previous `baseConfig`, an optional candidate
+contract (the current project contract is the default), and the same optional acknowledgement.
+It invokes the public classifier directly, is read-only, and marks a blocking result as an MCP
+error without maintaining separate adapter policy.

package/docs/demos/01-write-gate-self-correction.md

@@ -32,7 +32,7 @@ Add to the top of `src/domain/order.ts`:
 import { createInMemoryOrderRepository } from '../adapters/persistence/in-memory-order-repository.js';
 ```
 
-### 3. Run the CI gate (same stimulus as the write-gate hook)
+### 3. Run the CI gate (same architecture contract as the write-gate hook)
 
 ```bash
 npm run check
@@ -71,4 +71,4 @@ Expected:
 - The fix is a file move or port inversion — not editing `ark.config.json`.
 
 See also: [Break it on purpose](../../examples/hexagonal-order-api/README.md#break-it-on-purpose)
-for two more exercises.
+for two more exercises.

package/docs/enthusiast/README.md

@@ -32,12 +32,14 @@ aliases `ark` / `ark-check` still work).
 | **Reference** | [Commands and artifacts](reference-commands.md) | `--recommend`, `--write-plan`, `ark-adoption-plan.json`, fix-class JSON |
 | **Explanation** | [Why application shape matters](explanation-application-shape.md) | Understand shapes vs frameworks and progressive phases |
 
-## Public demos (Phase D)
+## Public demos
 
 Reproducible scripts — no video required:
 
 - [Write-gate self-correction](../demos/01-write-gate-self-correction.md)
 - [Brownfield baseline adoption](../demos/02-brownfield-baseline-adoption.md)
+- [Co-pilot autopilot, end to end](../demos/03-copilot-autopilot.md)
+
 ## Gallery starters
 
 | Archetype | Directory |
@@ -46,6 +48,8 @@ Reproducible scripts — no video required:
 | `api-backend` | [examples/api-backend-starter](../../examples/api-backend-starter/) |
 | `worker-pipeline` | [examples/worker-pipeline-starter](../../examples/worker-pipeline-starter/) |
 | `multi-app-workspace` | [examples/multi-app-workspace-starter](../../examples/multi-app-workspace-starter/) |
+| `vertical-slice-product` | [examples/vertical-slice-starter](../../examples/vertical-slice-starter/) |
+| `ddd-bounded-contexts` | [examples/ddd-context-starter](../../examples/ddd-context-starter/) |
 
 Deep teaching example (runnable API + break exercises): [hexagonal-order-api](../../examples/hexagonal-order-api/).
 

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

@@ -21,7 +21,7 @@ Installs:
 |------|-------------|
 | Claude Code | `.claude/settings.json`, `.claude/skills/` |
 | Cursor | `.cursor/mcp.json`, `.cursor/rules/ark.mdc`, `.cursor/commands/` |
-| Codex | `docs/ark-codex-config.toml` + home MCP/prompts |
+| Codex | `.codex/hooks.json`, `.agents/skills/`; MCP in `$CODEX_HOME/config.toml` |
 | **Grok Build** | `.grok/config.toml`, `.grok/hooks/`, `.grok/skills/` |
 
 See the [canonical host support matrix](../../README.md#host-enforcement-support) for the exact
@@ -42,10 +42,8 @@ npx arkgate-check --doctor
 npx arkgate-check --require-gates
 ```
 
-Doctor JSON (`--doctor --json`) includes **`writePath`**: the active host's supported profile,
-installed evidence, and whether PreToolUse is
-`repair` (machine-readable autoPatch on deny), `reject-only`, `mcp-only`, or
-`none` — plus `prepareWrite` / `autoPatch` booleans for leads.
+Doctor JSON includes `writePath.mode` plus `enforcementLadder`: support, installation, observed
+evidence, covered operations, bypassability, and CI honesty. MCP registration stays advisory.
 
 After upgrading the package, refresh skills so agents see the latest plan kinds:
 

package/docs/enthusiast/how-to-policy-pack.md

@@ -15,6 +15,9 @@ Available packs:
 - `enthusiast-layered`
 - `enthusiast-feature-sliced`
 - `enthusiast-monorepo`
+- `enthusiast-ui-surface`
+- `enthusiast-vertical-slice`
+- `enthusiast-ddd-bounded-contexts`
 
 ## Apply
 
@@ -34,4 +37,4 @@ Monorepo packs detect workspace roots from `package.json` / `pnpm-workspace.yaml
 | Application shape (todo app, API, …) | `ark-check --recommend` → `ark init --archetype` |
 | Preset name only | `--apply-policy-pack enthusiast-<preset>` |
 
-`ark-adoption-plan.json` from `--write-plan` includes a suggested `policyPack` id matching the recommended preset.
+`ark-adoption-plan.json` from `--write-plan` includes a suggested `policyPack` id matching the recommended preset.

package/docs/enthusiast/reference-archetypes.md

@@ -16,6 +16,8 @@ Authoritative source: `templates/architecture-playbook.json` (shipped in the npm
 | `integration-bridge` | System glue | `hexagonal` |
 | `multi-app-workspace` | Monorepo | `monorepo` |
 | `prototype-spike` | Quick experiment | `layered` |
+| `vertical-slice-product` | Feature-first product | `vertical-slice` |
+| `ddd-bounded-contexts` | Multiple business domains | `ddd-bounded-contexts` |
 
 ## Named presets
 
@@ -25,6 +27,9 @@ Authoritative source: `templates/architecture-playbook.json` (shipped in the npm
 | `layered` | `enthusiast-layered` |
 | `feature-sliced` | `enthusiast-feature-sliced` |
 | `monorepo` | `enthusiast-monorepo` |
+| `ui-surface` | `enthusiast-ui-surface` |
+| `vertical-slice` | `enthusiast-vertical-slice` |
+| `ddd-bounded-contexts` | `enthusiast-ddd-bounded-contexts` |
 
 ## Gallery mapping
 
@@ -33,4 +38,6 @@ Authoritative source: `templates/architecture-playbook.json` (shipped in the npm
 | `crud-product` | `examples/crud-product-starter/` |
 | `api-backend` | `examples/api-backend-starter/` |
 | `worker-pipeline` | `examples/worker-pipeline-starter/` |
-| `multi-app-workspace` | `examples/multi-app-workspace-starter/` |
+| `multi-app-workspace` | `examples/multi-app-workspace-starter/` |
+| `vertical-slice-product` | `examples/vertical-slice-starter/` |
+| `ddd-bounded-contexts` | `examples/ddd-context-starter/` |

package/docs/enthusiast/reference-commands.md

@@ -37,16 +37,22 @@ Pack metadata: `templates/policy-packs/enthusiast-*.json`.
 ## Init and verify
 
 ```bash
-arkgate start --yes                    # guided setup + plan
+arkgate start --yes                    # read-only setup preview with non-interactive defaults
+arkgate start --yes --apply            # apply exactly that preview
 ark init --archetype <id> --yes        # alias path
 arkgate-check --doctor [--json]
 arkgate-check --coverage [--json]
 arkgate-check --plan [--json]          # mechanical-safe vs judgment vs deferred
 arkgate-check --strict-config
+arkgate-check --strict-merge
+arkgate preflight --changes changes.json [--change-map map.json] --json
 arkgate-check --report out.html --beginner
 arkgate-check --watch
 ```
 
+In 3.1+, strict merge protects policy changes; preflight checks one complete batch without writing
+(`--change-map` adds structural convergence). MCP: `ark_policy_delta`, `ark_prepare_change`.
+
 ## Plan classes (`--plan --json`)
 
 | `class` | Agent may auto-apply? | Examples (`remediationKind`) |
@@ -62,4 +68,4 @@ When present on violations:
 - `fixClass` — e.g. `port-inversion`, `file-move`
 - `effort` — `small` | `medium`
 - `enthusiastHint` — plain English fix guidance
-- plan enrichment: `class`, `remediationKind`, `typeOnly`, `sourcePureTypeModule`, `targetTypeOnlyExports`, `namedBindingsTypeOnly`
+- plan enrichment: `class`, `remediationKind`, `typeOnly`, `sourcePureTypeModule`, `targetTypeOnlyExports`, `namedBindingsTypeOnly`

package/docs/package-surface.md

@@ -7,6 +7,8 @@
 In-repo `docs/` remains the package/agent reference. Source: GitHub; distribution: npm.
 
 This document is the consumer contract for **what is stable** vs **what is experimental**.
+It ships as the consumer contract linked from the npm README. The separate experimental-runtime
+hardening guide remains repository-hosted rather than duplicated in the gate tarball.
 
 ---
 
@@ -21,9 +23,16 @@ This document is the consumer contract for **what is stable** vs **what is exper
 | **Plan pattern B (P03+)** | `ark-check --plan --json` → `plan.patternBets[]`, `plan.goal.designWeak` | Additive. Each bet: `id`, `smellId`, `pilot`, `evidence`, `successSignal`, `killSwitch`, **`neverMechanicalSafe: true`**, `class: "judgment"`. **Never** auto-applied by loop/autoPatch; not a `remediationKind` mechanical-safe. `goal.met` remains edge honesty only. |
 | **Pilot loop (Q04)** | `plan.pilotLoop` / `doctor.pilotLoop` | Additive. When design-weak: `active`, `oneAtATime`, `neverMechanicalSafe`, **`nextPilot`** extraction-card fields (`pilotTarget`, `smellId`, `move`, `successSignal`, `killSwitch`, `doNot[]`). **One pilot → re-doctor**; never multi-pilot batch; never mechanical-safe. |
 | **AI-velocity eval (Q05)** | `npm run eval:ai-velocity` → `eval/ai-velocity-report.json` | Fixture-measured (no live LLM). Same feature scenario on design-weak vs golden-path arms; metric **`placementTurns`** (agent-equivalent). Golden must be strictly better. Method string lives next to the number. Does not weaken the gate. |
+| **Contract health (W01)** | `ark-check --doctor --json` → `doctor.contractHealth`; optional `.ark/contract-smell-acks.json` | Additive, **advisory only** — meta-lint of the contract itself (layer-name heuristics; imprecision costs a warning line, never a verdict); never changes the verdict, `designFitness`, or `patternBets`. Stable smell ids: `contract-bidirectional-allow`, `contract-peripheral-depends-core`, `contract-lateral-adapter-allow`, `contract-dead-rule`; each smell has `severity`, `evidence[]` (sorted, honest `…(+N more)` truncation), `fix`, `message`, plain-language `outcome`, and `acknowledgedEdges` (acks applied to that id). Acknowledgments live in the bounded sidecar (`{ acks: [{ id, edge, reason }] }`, ≤64 KB / ≤200 entries; bidirectional edges order-insensitive, exact two segments); `contractHealth.acknowledged` counts **applied** acks only (stale acks count 0). **Absent is normal**; malformed file or edge grammar → ignored + `ackFile.invalid` where applicable, never silent suppression. |
+| **Governance weight (W02)** | `ark-check --doctor --json` → `doctor.contractHealth.governanceWeight` | Additive, **advisory only** — raw facts (`declaredLayers`, `populatedLayers`, `governedFiles`, `rules`, `deniedEdges`, `allowedEdges`, `filesPerLayer`, `rulesPerLayer`) plus a fixed comparative band `weight: heavy | typical | light | unknown` and its fixed `note`. Fixed deterministic thresholds: **heavy** = fewer than 25 governed files per declared layer AND (6+ layers OR 4+ well-formed rules per layer); **light** = at most 2 layers over 150+ governed files; **unknown** = no layers or no governed files; everything else is **typical** (banding uses raw ratios; the reported ratios are rounded for display). `notAScore: true` is explicit: never a composite score, ranking, or gate input; the heavy note asks to justify NEW layers/rules and never suggests deleting working ones. Human doctor prints a line only for `heavy`/`light`. |
 | **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, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. |
-| **`arkgate/schema/analysis-result`** | Public CLI/MCP/hook diagnostic envelope (`schemaVersion`, `valid`, `diagnostics`) | Versioned JSON Schema; committed v1 compatibility fixture protects rule, severity, location, and evidence fields. |
+| **Policy transition analysis (T01, 3.1.0)** | `analyzePolicyDelta(...)`; MCP `ark_policy_delta`; CLI `--policy-base` / `--policy-base-ref` / `--policy-ack`; check JSON `policyDelta` | Additive schema `1.0`. Classifications and finding ids are deterministic. Weakening/judgment requires an acknowledgement bound to both policy hashes and the exact blocking finding set. |
+| **Atomic change preflight (T02, 3.1.0)** | `preflightChange(...)`; CLI `ark preflight --changes <file> --json`; MCP `ark_prepare_change` | Additive schema `1.0`. One complete governed production-source `{path,content}` / `{path,delete:true}` batch; read-only; returns operation, content/tree/policy/compiler fingerprints and stable graph findings. MCP availability alone is advisory. |
+| **Architecture change map (T03, 3.1.0)** | `arkgate/schema/change-map`; CLI `ark preflight --change-map <file>`; MCP `ark_prepare_change.changeMap` | Optional strict schema `1.0`. Canonical planned paths + operations + resolved Ark layers + dependencies between planned files. Preflight returns `changeMapHash`; absence is normal and adds no project file. Structural intent only, never behavioral completion. |
+| **Structural convergence (T04, 3.1.0)** | `analyzeArchitectureConvergence(...)`; map-enabled `preflightChange(...)`; existing CLI/MCP preflight adapters | Additive `convergence` result with stable `satisfied`, `missing`, `contradictory`, and `unplanned` findings. Uses the supplied/current project tree as base and the explicit complete change set as candidate; no implicit Git or LLM input. `readOnly: true`; `behavioralCompletion: "not-evaluated"`. Structural mismatch makes preflight invalid. |
+| **Enforcement ladder + fixed journey (T05, 3.1.0)** | `doctor.writePath.enforcementLadder`; hook repair `enforcement`; `npm run eval:change-integrity` | Additive schema `1.0` separates supported/installed/active/bypassable state and evidence. Hard is operation-scoped only for a supported covered hook; MCP is advisory; required CI status stays unverified locally. Fixed no-context fixture proves CLI/MCP/hook/final parity, one casual denial, acceptance behavior, and strict Ark. |
+| **`arkgate/schema/analysis-result`** | Public CLI/MCP/hook diagnostic envelope (`schemaVersion`, `valid`, `diagnostics`) | Schema `1.1` adds optional `nextAction`; the `1.0` fixture and consumer-owned TypeScript diagnostics remain valid. |
 | **Config JSON Schema** | `arkgate/schema` or `arkgate/schema/ark.config.schema.json` | Stable package resource subpaths for editor completion and contract tooling. |
 | **Agent skills** | `/ark-*` templates installed by `--install-agent-gates` | Skill *names* and “default flow” are stable; internal skill prose may evolve (e.g. When/not when, explore Shape dual-plan seed, extraction cards, day-zero origin order). |
 | **ESLint subpath** | `arkgate/eslint` | Config-driven layer/import rules; loads consumer `ark.config.json`. |
@@ -84,5 +93,6 @@ production deployment would need to satisfy; it is not a readiness certification
 
 ## Release notes (maintainers)
 
-Ship notes for a version live under [releases/](./releases/) (e.g. [2.12.0.md](./releases/2.12.0.md)).
+Ship notes for a version live under [releases/](./releases/) (latest:
+[3.2.0.md](./releases/3.2.0.md)).
 Publish path: signed annotated tag → GitHub Release → `publish-npm.yml` (see [CONTRIBUTING.md](../CONTRIBUTING.md)).

package/docs/threat-model.md

@@ -1,4 +1,4 @@
-# Threat model — ArkGate (Q9)
+# Threat model — ArkGate
 
 **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
@@ -27,21 +27,24 @@ infrastructure beyond how this package is published.
 
 | 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 |
+| T1 | Agent bypasses hook (direct `fs` / alternate tool) | Ungoverned code lands | CI gate; optional pre-commit (Q3); doctor ladder never upgrades installed files to active/hard proof |
 | 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 |
+| T3 | CI job missing / not required | Merge green without architecture | doctor `enforcement-ci-*` gaps; `--strict-merge`; required-status remains locally `unverified` |
+| T4 | Config weakened (`peerIsolation: false`, empty rules) | False green | semantic policy-delta guard in strict merge; hash-bound explicit acknowledgement; present-state safety diagnostics |
 | 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 |
+| T11 | Prompt context is mistaken for enforcement | Verdict changes after compaction or missing skills | contract/tree inputs only; no-context eval compares hashes and adapter evidence |
+| T12 | Partial multi-file hook validation misses a cross-file edge | Invalid batch reaches disk | complete `apply_patch` events use atomic preflight; incomplete/bypassable paths rely on CI |
 
 ## Trust boundaries
 
 ```
-Claude/Grok host --PreToolUse--> arkgate-mcp (hard matched-write boundary)
+Claude/Grok host --PreToolUse--> arkgate-mcp (hard only for observed covered operation)
+Codex ApplyPatch  --PreToolUse--> arkgate-mcp (atomic feedback; bypassable/non-hard host profile)
 Any MCP host     --tool call----> arkgate-mcp (advisory validation)
 Human IDE        --disk/git-----> working tree
 working tree     --PR-----------> CI ark-check --strict-merge
@@ -51,7 +54,8 @@ 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.
+- External adoption and independent-audit evidence are release snapshots bound to pinned commits;
+  they do not prove every repository layout or future host version.
 - Live multi-agent loop-cost remains optional (`ARK_EVAL_LOOP_LIVE`).
 
 ## Verification hooks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "3.0.5",
+  "version": "3.2.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -26,6 +26,8 @@
     "./schema/ark.config.schema.json": "./schemas/ark.config.schema.json",
     "./schema/analysis-result": "./schemas/ark.analysis-result.schema.json",
     "./schema/ark.analysis-result.schema.json": "./schemas/ark.analysis-result.schema.json",
+    "./schema/change-map": "./schemas/ark.change-map.schema.json",
+    "./schema/ark.change-map.schema.json": "./schemas/ark.change-map.schema.json",
     "./nestjs": {
       "types": "./compat/nestjs.d.ts",
       "import": "./compat/nestjs.js",
@@ -50,16 +52,14 @@
     "schemas",
     "docs/agent-guide.md",
     "docs/enthusiast",
-    "docs/demos",
+    "docs/demos/01-write-gate-self-correction.md",
+    "docs/demos/02-brownfield-baseline-adoption.md",
     "docs/ai-gates.md",
-    "docs/migrate-from-ark-runtime-kernel.md",
     "docs/typescript-support.md",
-    "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",
@@ -105,6 +105,7 @@
     "eval:comparative": "node eval/comparative-run.mjs",
     "eval:loop-cost": "node eval/loop-cost-run.mjs",
     "eval:ai-velocity": "node eval/ai-velocity-run.mjs",
+    "eval:change-integrity": "node eval/change-integrity-run.mjs",
     "eval:adoption": "node eval/adoption-run.mjs",
     "test:adoption-harness": "vitest run tests/unit/eval/adoptionHarness.test.ts",
     "bench:scale": "node scripts/ark-scale-bench.mjs",
@@ -119,7 +120,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "typescript": "^5.9.3"
+    "typescript": ">=5.0.0 <8"
   },
   "peerDependencies": {
     "@arkgate/runtime": ">=0.1.0-experimental.0 <1",

package/schemas/ark.analysis-result.schema.json

@@ -11,7 +11,7 @@
   ],
   "properties": {
     "schemaVersion": {
-      "const": "1.0"
+      "const": "1.1"
     },
     "valid": {
       "type": "boolean"
@@ -83,6 +83,10 @@
                 "type": "boolean"
               }
             }
+          },
+          "nextAction": {
+            "type": "string",
+            "minLength": 1
           }
         }
       }

package/schemas/ark.change-map.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/arkgate@3/schemas/ark.change-map.schema.json",
+  "title": "ArkGate architecture change map",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$schema",
+    "schemaVersion",
+    "files"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "minLength": 1,
+      "default": "https://unpkg.com/arkgate@3/schemas/ark.change-map.schema.json"
+    },
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0",
+      "default": "1.0"
+    },
+    "files": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "operation",
+          "layer"
+        ],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
+          "operation": {
+            "type": "string",
+            "enum": [
+              "create",
+              "update",
+              "delete"
+            ]
+          },
+          "layer": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "dependencies": {
+      "type": "array",
+      "default": [],
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "from",
+          "to"
+        ],
+        "properties": {
+          "from": {
+            "type": "string",
+            "minLength": 1
+          },
+          "to": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    }
+  }
+}

package/server.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.pedroknigge/arkgate",
-  "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI, plan/loop)",
+  "description": "ArkGate \u2014 architecture co-pilot for AI TypeScript (write gate, CI, plan/loop)",
   "repository": {
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "3.0.5",
+  "version": "3.2.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "3.0.5",
+      "version": "3.2.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"