arkgate 3.0.5 → 3.1.0

package/CHANGELOG.md

@@ -4,7 +4,53 @@ All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are do
 
 ## Unreleased
 
-No changes are scheduled after 3.0.5.
+## 3.1.0 — 2026-07-15
+
+Deterministic change integrity. **No breaking** CLI or `ark.config.json` changes. **No gate
+weaken.**
+
+### Added
+
+- **T01 policy-transition guard:** the public analysis API and generated CLI engine classify
+  `ark.config.json` changes as `strengthening`, `neutral`, `judgment-required`, or `weakening`.
+  `--strict-merge` compares the Git merge-base contract when available; explicit
+  `--policy-base` / `--policy-base-ref` inputs are also supported.
+- **Hash-bound acknowledgement:** weakening and judgment-required findings fail until
+  `--policy-ack` supplies the exact base/candidate policy hashes, complete finding-id set, and a
+  non-empty reason. Any later contract edit invalidates the acknowledgement.
+- **CI base provenance:** generated workflows fetch full history and the composite Action passes
+  the PR/push base SHA through `ARK_POLICY_BASE_REF`.
+- **MCP parity:** `ark_policy_delta` exposes the same read-only classifier for explicit base and
+  candidate contracts and returns blocking transitions as tool errors.
+- **T02 atomic change preflight:** public `preflightChange(...)`, CLI
+  `ark preflight --changes <change-set.json>`, and MCP `ark_prepare_change` evaluate one complete
+  create/update/delete candidate without writing. Schema `1.0` includes per-file content
+  fingerprints plus policy, compiler, base-tree, and candidate-tree fingerprints.
+- **Batch safety:** duplicate normalized paths, stale delete targets, lexical root escapes, and
+  symlink escapes fail closed; cross-file forbidden edges and cycles are reported before commit.
+- **T03 optional architecture change map:** strict schema `1.0` describes canonical operations,
+  resolved layers, and local edges. CLI/MCP preflight binds its deterministic hash; no map is
+  installed by default. Both published schema subpaths are parity-checked with the Domain contract.
+- **T04 honest structural convergence:** map-enabled preflight compares the explicit complete
+  candidate with the current supplied base through the shared analysis IR. Stable findings separate
+  satisfied, missing, contradictory, and unplanned file/edge work; structural drift rejects the
+  batch without writes, while every result states behavioral completion was not evaluated.
+- **T05 actionable, context-independent enforcement:** blocking diagnostics expose one deterministic
+  `nextAction` across JSON and human output. Doctor and hook repair JSON separate supported,
+  installed, active, and bypassable enforcement with evidence and operation coverage; MCP-only and
+  locally unverifiable required-status state remain labeled honestly.
+- **Complete-patch hook parity:** governed Codex `ApplyPatch` create/update/delete sets use the same
+  atomic preflight as CLI/MCP before per-file safety checks, catching batch-only edges and cycles.
+  Codex remains advisory/bypassable at the host level.
+- **Fixed Phase T evaluation:** `npm run eval:change-integrity` proves identical no-context hashes and
+  verdicts, CLI/MCP/hook/final diagnostic parity, one concise casual denial, prewritten feature
+  acceptance, and strict Ark green without a live LLM or required planning file.
+### Fixed
+
+- **Compatibility/release:** analysis-result `1.1` preserves `1.0` TypeScript values; first-push
+  zero SHAs and resumable npm release assets are handled safely.
+
+Release note: `docs/releases/3.1.0.md`.
 
 ## 3.0.5 — 2026-07-14
 

package/README.md

@@ -136,7 +136,7 @@ npx arkgate-check --install-agent-gates --force
 npx arkgate-check --doctor
 ```
 
-Full checklist (CI, MCP, Codex, imports): **[docs/migrate-from-ark-runtime-kernel.md](docs/migrate-from-ark-runtime-kernel.md)**.
+Full checklist (CI, MCP, Codex, imports): **[migrate-from-ark-runtime-kernel.md](https://github.com/pedroknigge/arkgate/blob/main/docs/migrate-from-ark-runtime-kernel.md)**.
 
 ---
 
@@ -199,6 +199,20 @@ constrain + validate + optional `autoPatch` + `judgmentBrief`). PreToolUse hooks
 never silent write). Cursor/Codex MCP calls remain advisory. See
 [docs/ai-gates.md](docs/ai-gates.md).
 
+For a complete multi-file architecture-source candidate, use MCP **`ark_prepare_change`** or
+`ark preflight --changes change-set.json --json`. Creates, updates, and deletes are evaluated as
+one read-only graph, so an edge or cycle that appears only across the batch is rejected before any
+project file is written. With `--change-map map.json` (or MCP `changeMap`), the same verdict also
+classifies planned structure as satisfied, missing, contradictory, or unplanned. This is structural
+convergence only: behavioral completion is always reported as not evaluated.
+
+Every blocking diagnostic carries stable rule/location/evidence fields plus one deterministic
+`nextAction`; human CLI/hook text prints that same action. A complete Codex `ApplyPatch` payload is
+reconstructed and sent through the same atomic engine before per-file safety checks. Codex remains
+honestly bypassable/advisory because not every Code Mode write dispatches the project hook. The
+verdict depends only on the explicit contract and candidate—not `AGENTS.md`, skills, injected prose,
+or an LLM.
+
 | Need | Skill | Not |
 |------|--------|-----|
 | Only the apply loop for plan **A** (edges) | `/ark-loop` | empty A + design residual → explore |
@@ -245,12 +259,16 @@ ark.config.json
 
 - **Presets:** hexagonal, layered, feature-sliced, monorepo, ui-surface, vertical-slice, ddd-bounded-contexts (+ aliases clean-architecture / onion-architecture). Layers start optional; doctor suggests tightening populated cores. Cross-slice / cross-context bans use optional `peerIsolation` rules.
 - **Versioned config:** generated contracts include `$schema` + `schemaVersion`; CLI, MCP, and
-  ESLint validate through the same loader. Unknown keys fail with their JSON path. See the
-  [configuration and editor guide](docs/configuration.md).
+  ESLint validate through the same loader. Unknown keys fail with their JSON path. Strict merge
+  also compares the contract transition and blocks unacknowledged weakening with hashes and stable
+  finding ids. See the [configuration and editor guide](docs/configuration.md).
 - **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:** `ark start` asks for (or detects) one active host and writes one compact router, not copied skill packs, in at most five project files and 25 KB. Use `ark-check --install-agent-gates --skills-only --tools <host>` later when you explicitly want the full `/ark-*` skill set. Reports are opt-in with `ark-check --report`.
 - **Write protocol (2.10 / Track W):** mechanical-safe **autoPatch** on the write gate (`import type`); MCP **`ark_prepare_write`** (place + validate + patch + judgmentBrief); opt-in hook **`--hook-repair`** (`ARK_REPAIR_JSON`); doctor **`writePath`** (repair vs reject-only); loop-cost eval (`npm run eval:loop-cost`). Port-proof inject is **judgment** (arity change), not silent auto-apply.
+- **Enforcement ladder (Phase T):** doctor JSON exposes `writePath.enforcementLadder` with separate
+  `supported`, `installed`, `active`, `bypassable`, evidence, operation coverage, and required-status
+  honesty. Hook repair JSON carries the operation-scoped ladder; MCP alone remains advisory.
 - **Fail-closed CI (2.11):** `--strict-merge` combines config coverage, shared gate-file
   presence, and bypass diagnostics for dynamic imports, TypeScript suppressions, explicit `any`
   casts, InMemory runtime defaults, and disabled peer isolation. `--strict` is a compatibility
@@ -288,12 +306,14 @@ npx arkgate start --tools codex --apply   # select the host explicitly
 npx arkgate start --install --apply       # also add arkgate to package.json (explicit only)
 npx arkgate start --remove-host codex     # preview compact-host removal; add --apply to confirm
 npx arkgate-check --doctor                # health + Adoption gaps (not just fitness)
-npx arkgate-check --doctor --json         # machine-readable doctor.adoption
+npx arkgate-check --doctor --json         # adoption + explicit writePath.enforcementLadder
 npx arkgate-check --strict                # fail-closed CI + installed-gate/safety checks
 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 (opens in browser on local TTY; --no-open to skip)
 npx arkgate-check --baseline              # only NEW violations fail
+npx arkgate preflight --changes changes.json --json  # atomic read-only batch verdict
+npx arkgate preflight --changes changes.json --change-map map.json --json  # intent hash + structural convergence
 npx arkgate upgrade                       # package + gates/skills + MCP/Codex normalize
 ```
 
@@ -314,7 +334,7 @@ separate experimental package:
 
 ```ts
 import { createStrictArkKernelFromConfig } from '@arkgate/runtime';
-// see docs/production-hardening.md and docs/package-surface.md
+// see the repository production-hardening and package-surface guides
 ```
 
 The stable `arkgate` package does not bundle runtime implementation. The deprecated
@@ -328,7 +348,7 @@ The kernel’s default stores (`InMemoryEventBuffer`, `InMemoryAuditStore`,
 `InMemoryReadModelStore`, `InMemoryWorkflowStore`) are **reference in-memory only**:
 fine for tests, demos, and single-process local work — they **do not** survive restarts
 and are **not** production durability. Implement the store interfaces (or inject your own)
-for real systems. Details: [docs/production-hardening.md](docs/production-hardening.md).
+for real systems. Details: [production-hardening.md](https://github.com/pedroknigge/arkgate/blob/main/docs/production-hardening.md).
 
 ---
 
@@ -340,12 +360,12 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | **Package surface (stable vs experimental)** | [docs/package-surface.md](docs/package-surface.md) |
 | Wire Claude / Cursor / Codex / Grok + **ESLint (CI-parity)** | [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) |
+| Migrate from `ark-runtime-kernel` | [docs/migrate-from-ark-runtime-kernel.md](https://github.com/pedroknigge/arkgate/blob/main/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/) |
 | Examples | [examples/](examples/README.md) |
-| Release 3.0.0 | [release notes and publication checklist](docs/releases/3.0.0.md) |
+| Latest release (3.1.0) | [release notes](docs/releases/3.1.0.md) · [3.0.0 baseline](docs/releases/3.0.0.md) |
 | Roadmap | [ROADMAP.md](ROADMAP.md) · [Changelog](CHANGELOG.md) |
 
 ---
@@ -363,7 +383,7 @@ 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 for one major).
-MCP registry: `io.github.pedroknigge/arkgate`.
+MCP registry: [`io.github.pedroknigge/arkgate`](https://registry.modelcontextprotocol.io/) (`server.json` @ package version).
 **Source:** [github.com/pedroknigge/arkgate](https://github.com/pedroknigge/arkgate)
 
 Node ≥ 18 · **MIT**.

package/bin/ark-check.mjs

@@ -99,6 +99,7 @@ import {
 } from './lib/config-warnings.mjs';
 import { runArchitectureScan } from './lib/architecture-scan.mjs';
 import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
+import { analyzePolicyTransition } from './lib/policy-delta-io.mjs';
 
 
 function parseArgs(argv) {
@@ -110,6 +111,7 @@ function parseArgs(argv) {
     tsconfig: undefined,
     json: false,
     strictConfig: false,
+    strictMerge: false,
     requireGates: false,
     requireWriteHook: undefined,
     init: false,
@@ -119,6 +121,9 @@ function parseArgs(argv) {
     force: false,
     skillsOnly: false,
     baseline: undefined,
+    policyBase: undefined,
+    policyBaseRef: undefined,
+    policyAck: undefined,
     updateBaseline: false,
     noCache: false,
     coverage: false,
@@ -149,6 +154,7 @@ function parseArgs(argv) {
     else if (arg === '--strict' || arg === '--strict-merge') {
       args.strictConfig = true;
       args.requireGates = true;
+      args.strictMerge = true;
     }
     else if (arg === '--strict-config') args.strictConfig = true;
     else if (arg === '--require-gates') args.requireGates = true;
@@ -205,6 +211,9 @@ function parseArgs(argv) {
       const next = argv[i + 1];
       args.baseline = next && !next.startsWith('-') ? argv[++i] : '.ark-baseline.json';
     }
+    else if (arg === '--policy-base') args.policyBase = requireValue(arg, i++);
+    else if (arg === '--policy-base-ref') args.policyBaseRef = requireValue(arg, i++);
+    else if (arg === '--policy-ack') args.policyAck = requireValue(arg, i++);
     else if (arg === '--root') args.root = path.resolve(requireValue(arg, i++));
     else if (arg === '--config') args.config = requireValue(arg, i++);
     else if (arg === '--manifest') args.manifest = requireValue(arg, i++);
@@ -230,7 +239,7 @@ function usage() {
   return [
     'Usage: arkgate-check | ark-check  (identical bins; product name ArkGate)',
     '       ark-check --version',
-    '       ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-merge | --strict | --strict-config] [--require-gates] [--require-write-hook <host>] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
+    '       ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-merge | --strict | --strict-config] [--policy-base <file> | --policy-base-ref <git-ref>] [--policy-ack <file>] [--require-gates] [--require-write-hook <host>] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
     '       ark-check --coverage [--json]          per-layer file counts + full unclassified list (report only, exit 0)',
     '       ark-check --plan [--json]              classified remediation plan (mechanical-safe / judgment / deferred) + goal; report only',
     '       ark-check --recommend [--json] [--write-plan]  application-shape plan; --write-plan emits ark-adoption-plan.json',
@@ -287,6 +296,10 @@ function usage() {
     'Use --strict-merge for the fail-closed CI profile: --strict-config + --require-gates',
     'plus the security diagnostics surfaced by doctor. --strict is a compatibility alias.',
     'This merge profile never depends on an editor/agent hook.',
+    'When a Git merge base is available, --strict-merge classifies the ark.config.json',
+    'transition. Weakening or judgment-required findings fail unless --policy-ack names',
+    'every finding and is bound to both policy hashes. Use --policy-base/--policy-base-ref',
+    'for an explicit comparison; ARK_POLICY_BASE_REF is the CI environment equivalent.',
     'Add --require-write-hook claude|grok to validate a hard local write boundary for that',
     'specific host. Cursor and Codex expose advisory MCP tools plus the shared CI check;',
     'merge blocking requires repository policy to make that status required.',
@@ -1060,6 +1073,15 @@ async function main() {
 
   const root = args.root;
   const config = readConfig(root, args.config);
+  const policyDelta = analyzePolicyTransition({
+    root,
+    configPath: args.config,
+    candidateConfig: config,
+    strictMerge: args.strictMerge,
+    basePath: args.policyBase,
+    baseRef: args.policyBaseRef,
+    acknowledgementPath: args.policyAck,
+  });
   const manifest = readManifest(root, args.manifest);
   const rules = manifest?.architecture?.rules ?? config.rules;
   const files = collectGovernedFiles(root, config);
@@ -1216,7 +1238,9 @@ async function main() {
   // Soft/advisory warnings (failsStrict === false) never fail --strict-config.
   const strictWarnings = warnings.filter((w) => w.failsStrict !== false);
   const ok =
-    activeViolations.length === 0 && (!args.strictConfig || strictWarnings.length === 0);
+    activeViolations.length === 0 &&
+    (!args.strictConfig || strictWarnings.length === 0) &&
+    (policyDelta?.valid ?? true);
 
   if (args.plan) {
     const cov = computeCoverage(root, config, files, rules);
@@ -1384,6 +1408,7 @@ async function main() {
           }
         : {}),
       ...(codexRepoSkillGap ? { codexRepoSkillGap } : {}),
+      ...(policyDelta ? { policyDelta } : {}),
     }, null, 2));
   } else {
     for (const warning of warnings) {
@@ -1402,7 +1427,22 @@ async function main() {
         )
       );
     }
-    if (activeViolations.length === 0) {
+    if (policyDelta && !policyDelta.valid) {
+      for (const finding of policyDelta.findings.filter(
+        ({ classification }) =>
+          classification === 'weakening' || classification === 'judgment-required'
+      )) {
+        console.error(
+          `${color.red('policy')} ${finding.classification} ${finding.path}: ${finding.message}`
+        );
+        console.error(`  Next: ${finding.nextAction}`);
+      }
+      console.error(
+        `Policy transition blocked (${policyDelta.basePolicyHash} → ${policyDelta.candidatePolicyHash}). ` +
+          'Provide --policy-ack with the exact hashes, finding ids, and a non-empty reason.'
+      );
+    }
+    if (activeViolations.length === 0 && (policyDelta?.valid ?? true)) {
       const advisoryOnly = warnings.length > 0 && strictWarnings.length === 0;
       if (warnings.length === 0) {
         console.log(`${color.green('✔')} Ark check passed.${baselineNote}`);
@@ -1421,7 +1461,9 @@ async function main() {
       }
     } else {
       console.error(
-        `${color.red('✖')} ${activeViolations.length} violation(s).${baselineNote}`
+        activeViolations.length > 0
+          ? `${color.red('✖')} ${activeViolations.length} violation(s).${baselineNote}`
+          : `${color.red('✖')} Policy transition rejected.${baselineNote}`
       );
     }