arkgate 3.0.5 → 3.2.0

package/CHANGELOG.md

@@ -4,7 +4,98 @@ All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are do
 
 ## Unreleased
 
-No changes are scheduled after 3.0.5.
+## 3.2.0 — 2026-07-15
+
+Contract health (Phase W): ArkGate now also meta-lints the contract itself and describes its
+governance weight, and the docs name the enforcement-boundary trade-off explicitly. Everything in
+this release is **advisory only** — no verdict, `designFitness`, `patternBets`, or gate result
+changes. **No breaking** CLI or `ark.config.json` changes. **No gate weaken.**
+
+### Added
+
+- **W01 contract smells:** `ark-check --doctor --json` gains `doctor.contractHealth` with four
+  stable, deterministic smell ids that lint the contract rather than 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), and `contract-dead-rule` (rule referencing an unknown or empty layer, or
+  a same-layer no-op; `optional: true` layers are exempt). Each smell carries `severity`,
+  sorted `evidence[]` with honest `…(+N more)` truncation, technical `message`, plain-language
+  `outcome`, and `fix`. Human doctor prints a "Contract health (advisory)" section.
+- **Acknowledgment sidecar:** deliberate edges are recorded in an optional
+  `.ark/contract-smell-acks.json` (`{ acks: [{ id, edge, reason }] }`; bidirectional edges
+  order-insensitive) — the versioned `ark.config.json` schema is untouched. The file is bounded
+  (≤64 KB, ≤200 entries); a malformed file or edge grammar is reported via `ackFile.invalid` and
+  never suppresses a smell. `contractHealth.acknowledged` counts applied acks only.
+- **W02 governance weight:** `doctor.contractHealth.governanceWeight` reports raw facts
+  (declared/populated layers, governed files, rules, denied/allowed edges, files-per-layer,
+  rules-per-layer) plus a fixed comparative band — `heavy` (fewer than 25 governed files per layer
+  AND 6+ layers or 4+ rules per layer), `light` (≤2 layers over 150+ governed files), `typical`,
+  or `unknown` — with fixed wording and an explicit `notAScore: true`. Banding uses raw ratios;
+  reported ratios are rounded for display. The heavy note asks to justify NEW layers with
+  demonstrated pressure and never suggests deleting working ones.
+- **W03 enforcement-boundary positioning:** README explains why the hard guarantee lives at the
+  required merge status ("deliberate trade-off, not a gap"; the contract doubles as a pressure
+  sensor), and `docs/ai-gates.md` / `docs/agent-guide.md` carry the same framing next to the
+  canonical host support matrix. A docs regression pins the wording without strengthening any
+  guarantee claim.
+
+### Fixed
+
+- Contract meta-lint reads the rules actually in force (manifest-aware), not only `config.rules`.
+- Hostile ack-file inputs (FIFO/symlink targets, oversized files, sloppy edge strings) can no
+  longer hang `--doctor`, exhaust memory, or silently suppress findings; null rule entries and
+  malformed coverage rows no longer throw.
+- Governance-weight banding is size-relative in both clauses: a large tree with a proportionate
+  dense rule matrix never reads `heavy`, and NaN/negative counts read `unknown`.
+
+## 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

@@ -16,8 +16,9 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 3.0** passed its independent beta-exit audit. The npm badge reports the version
-> currently available in the registry.
+> **ArkGate 3.2.0** is current stable: contract health (advisory meta-lint of the contract +
+> governance weight), on top of 3.1's policy-transition checks, atomic multi-file preflight, and
+> optional structural convergence. [Release notes](docs/releases/3.2.0.md).
 
 ---
 
@@ -136,7 +137,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)**.
 
 ---
 
@@ -156,7 +157,7 @@ Aliases `ark` / `ark-check` / `ark-mcp` still work. **npm / pnpm / yarn**. No in
 <details>
 <summary>What <code>/ark-autopilot</code> does under the hood (optional detail)</summary>
 
-1. Setup if needed (`ark start` — compact contract + active-host router + CI gate; create an HTML/origin report explicitly when you need one).
+1. Setup if needed (`ark start` previews; review, then `ark start --apply`).
 2. **Explore pass** (decision-grade map of *this* product; field path when demos exist).
 3. **Dual plan:** **A** remediation from `--plan` (mechanical-safe only by default); **B** pattern/evolution bets (never auto-applied as mechanical-safe). Empty plan ≠ “healthy” without explore/B.
 4. Apply A → re-check; judgment only when you ask for full apply.
@@ -199,6 +200,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 |
@@ -229,6 +244,22 @@ Brownfield phases: **Align** (honest contract) → **Stabilize** (real baseline)
 This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair payloads never write code silently: the host must re-inject the candidate and ArkGate revalidates it. Run `arkgate-check --doctor` for the evidence actually detected in the current repository.
 <!-- arkgate-host-support:end -->
 
+#### Why the hard guarantee lives at the merge gate
+
+The split above is a deliberate trade-off, not a gap. ArkGate validates at the earliest boundary
+each host offers and enforces at the earliest boundary a repository can make non-bypassable: the
+required merge status. Hard hooks (Claude Code, Grok Build) deny the listed write operations at
+write time; advisory surfaces (MCP, rules) coach the agent while it works. But any local boundary
+can be routed around — another tool, a direct filesystem write, a human edit — so the only
+guarantee ArkGate claims for every path is the `arkgate-check --strict-merge` check, and only when
+the repository makes that status required. Local checks optimize feedback speed; the merge gate
+owns correctness.
+
+A useful consequence: the contract doubles as a pressure sensor. Recurring violations or baseline
+exceptions concentrated on one layer edge are evidence that the current design stopped fitting the
+code — a reason to reshape the contract deliberately (start with `/ark-explore`), never to weaken
+the gate.
+
 Detailed setup: [docs/ai-gates.md](docs/ai-gates.md).
 
 ---
@@ -245,22 +276,25 @@ 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`.
+- **Agents:** `ark start` previews one compact active-host router (≤5 files / 25 KB); `--apply`
+  writes those exact bytes. Full skills remain explicit via `--install-agent-gates --skills-only`;
+  reports remain opt-in via `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
   alias. Neither requires an editor hook; use `--require-write-hook claude|grok` when that local
   guarantee is part of the check.
-- **Trust / coverage (3.0 release baseline):** package unit-test floors on the broad product surface
-  (statements/lines **≥80%**, branches/functions **≥85%**; enforcement-critical modules **≥95%**
-  branch). The V05 beta-exit audit passed with 12 pinned public adoptions, 97% median governed
-  coverage, and zero P0/P1 findings. Stable publication remains the signed-tag, GitHub Release,
-  and provenance-backed npm workflow documented in [the 3.0.0 release notes](docs/releases/3.0.0.md).
+- **Release evidence:** independent 3.0 audit baseline plus signed-tag, GitHub Release, and
+  provenance-backed npm publication; see the [3.1.0 release notes](docs/releases/3.1.0.md).
 - **TypeScript:** project compilers 5.x / 6.x / 7.x — gate falls back to a nested JS-API TypeScript when TS 7’s main export is version-only ([docs/typescript-support.md](docs/typescript-support.md)).
 
 ### Why not only ESLint / dependency-cruiser / Nx?
@@ -288,12 +322,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 +350,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 +364,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).
 
 ---
 
@@ -337,16 +373,17 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Audience | Link |
 |----------|------|
 | New builders (plain language) | [docs/enthusiast/](docs/enthusiast/README.md) |
-| **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) |
+| **Package surface and configuration** | [package policy](docs/package-surface.md) · [contract](docs/configuration.md) |
+| Wire agents + **ESLint (CI-parity)** | [docs/ai-gates.md](docs/ai-gates.md) · [threat model](docs/threat-model.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) |
+| Security reporting | [SECURITY.md](SECURITY.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) |
-| Roadmap | [ROADMAP.md](ROADMAP.md) · [Changelog](CHANGELOG.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 and decisions | [ROADMAP.md](ROADMAP.md) · [ADRs](docs/adr/) · [Changelog](CHANGELOG.md) |
 
 ---
 
@@ -363,7 +400,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}`
       );
     }