arkgate 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -4,6 +4,51 @@ All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are do
 
 ## Unreleased
 
+## 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

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).
 
 ---
 
@@ -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.
@@ -243,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).
 
 ---
@@ -264,7 +281,9 @@ ark.config.json
   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
@@ -274,11 +293,8 @@ ark.config.json
   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?
@@ -357,16 +373,17 @@ for real systems. Details: [production-hardening.md](https://github.com/pedrokni
 | 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](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) |
 | 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) |
+| Roadmap and decisions | [ROADMAP.md](ROADMAP.md) · [ADRs](docs/adr/) · [Changelog](CHANGELOG.md) |
 
 ---
 

package/bin/lib/contract-smells.mjs

@@ -0,0 +1,514 @@
+/**
+ * Deterministic contract smells (Phase W / W01) — meta-lint of ark.config.json itself.
+ *
+ * ArkGate validates code against the contract; these sensors validate the contract
+ * against known contract anti-patterns: rule shapes that permit future degradation
+ * even at 0 violations. Advisory only — they never change a pass/fail verdict, never
+ * feed designWeak/patternBets, and never block a gate. Complements `soft-contract`
+ * (missing rules) by detecting *permissive or unused* rules.
+ *
+ * Acknowledgments live in an optional sidecar (`.ark/contract-smell-acks.json`,
+ * Q03 golden-pattern precedent) so the versioned config contract is untouched.
+ * A malformed ack file (or a malformed edge inside it) never suppresses a smell.
+ *
+ * Known limit (documented, deliberate): layer roles are inferred from layer NAMES
+ * via substring heuristics — a name like "Auditorium" reads as audit-ish. The
+ * surface is advisory, so a miss costs a warning line, never a verdict.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Stable contract-smell ids (doctor JSON `contractHealth` + skills). */
+export const CONTRACT_SMELL_IDS = Object.freeze([
+  'contract-bidirectional-allow',
+  'contract-peripheral-depends-core',
+  'contract-lateral-adapter-allow',
+  'contract-dead-rule',
+]);
+
+/** Plain-language outcome per id (Q02 pattern: outcome first, technical detail in message). */
+export const CONTRACT_SMELL_OUTCOMES = Object.freeze({
+  'contract-bidirectional-allow':
+    'Two layers may depend on each other in both directions — nothing stops a dependency cycle from growing there. Keep one direction, or acknowledge the loop explicitly with the reason.',
+  'contract-peripheral-depends-core':
+    'An observability/audit-style layer is allowed to reach into orchestration or persistence — it can quietly become a second orchestrator. Keep periphery consuming events/ports, not core internals.',
+  'contract-lateral-adapter-allow':
+    'One adapter layer may import another adapter family directly — shared mappers/aliases will pile up in the wrong place. Move shared shapes into Domain (or a shared kernel) instead of adapter-to-adapter reach.',
+  'contract-dead-rule':
+    'A rule enforces nothing: it points at a layer that matches no files or does not exist, or both sides are the same layer. Fix the layer patterns or delete the rule.',
+});
+
+export const CONTRACT_SMELL_ACKS_PATH = '.ark/contract-smell-acks.json';
+
+/** Hostile-input bounds (mirrors design-smells MAX_FILE_BYTES discipline). */
+const MAX_ACK_BYTES = 64 * 1024;
+const MAX_ACK_ENTRIES = 200;
+const MAX_EVIDENCE = 12;
+const MAX_MESSAGE_EDGES = 6;
+
+const PERIPHERAL_LAYER_RE = /observab|audit|telemetry|monitor|logging|metric|tracing/i;
+const CORE_TARGET_RE = /application|orchestr|persist|repositor/i;
+const ADAPTER_LAYER_RE = /adapter|persist|integrat|infra|gateway/i;
+
+/** Collision-safe internal key for a directed edge (layer names are arbitrary strings). */
+function directedKey(from, to) {
+  return JSON.stringify([from, to]);
+}
+
+/** Display + ack pair key. Only meaningful when neither name embeds the delimiter. */
+function pairLabel(a, b) {
+  return [a, b].sort().join('<->');
+}
+
+/** Names embedding the arrow delimiter cannot be matched safely from ack strings. */
+function ackMatchable(...names) {
+  return names.every((n) => typeof n === 'string' && !n.includes('->'));
+}
+
+/**
+ * Load the optional acknowledgment sidecar. Bounded and fail-loud:
+ * non-file, oversized, unparsable, or wrong-shaped content → `invalid: true`
+ * with `acks: []` (a broken file never suppresses anything).
+ *
+ * @param {string} root
+ * @returns {{ path: string, exists: boolean, invalid?: boolean, error?: string, acks: Array<{id: string, edge: string, reason?: string}> }}
+ */
+export function loadContractSmellAcks(root) {
+  const relPath = CONTRACT_SMELL_ACKS_PATH;
+  const abs = path.join(root, relPath);
+  let stats;
+  try {
+    stats = fs.statSync(abs);
+  } catch {
+    return { path: relPath, exists: false, acks: [] };
+  }
+  const invalid = (error) => ({ path: relPath, exists: true, invalid: true, error, acks: [] });
+  if (!stats.isFile()) return invalid('not a regular file');
+  if (stats.size > MAX_ACK_BYTES) return invalid(`larger than ${MAX_ACK_BYTES} bytes`);
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(abs, 'utf8'));
+  } catch (error) {
+    return invalid(error instanceof Error ? error.message : 'unreadable JSON');
+  }
+  const acks = Array.isArray(parsed?.acks) ? parsed.acks : null;
+  if (!acks) return invalid('expected { acks: [{ id, edge, reason? }] }');
+  if (acks.length > MAX_ACK_ENTRIES) return invalid(`more than ${MAX_ACK_ENTRIES} entries`);
+  const wellFormed = acks.every(
+    (a) =>
+      a !== null &&
+      typeof a === 'object' &&
+      typeof a.id === 'string' &&
+      typeof a.edge === 'string' &&
+      a.edge.trim().length > 0
+  );
+  if (!wellFormed) return invalid('every ack needs string id and non-empty string edge');
+  return { path: relPath, exists: true, acks };
+}
+
+/**
+ * Normalize an ack edge string; returns null (never matches) for malformed grammar,
+ * e.g. `A<->B<->C` — a sloppy edge must not suppress a real smell.
+ */
+function normalizeAckEdge(id, edge) {
+  const raw = String(edge).trim();
+  if (id === 'contract-bidirectional-allow') {
+    if (!raw.includes('<->')) return null;
+    const parts = raw.split('<->').map((s) => s.trim());
+    if (parts.length !== 2 || parts.some((p) => p.length === 0)) return null;
+    return pairLabel(parts[0], parts[1]);
+  }
+  return raw;
+}
+
+function isAcknowledged(ackState, id, canonicalEdge) {
+  if (!ackState || ackState.invalid || !Array.isArray(ackState.acks)) return false;
+  if (canonicalEdge == null) return false;
+  return ackState.acks.some((a) => a.id === id && normalizeAckEdge(id, a.edge) === canonicalEdge);
+}
+
+/**
+ * Core analysis: smells plus the count of ack entries that actually matched a
+ * detected edge (stale/typo acks match nothing and count nothing).
+ *
+ * @param {object} config ark.config (layers; rules unless overridden)
+ * @param {object|null} coverage computeCoverage result (layer file counts); optional
+ * @param {object} [ackState] result of loadContractSmellAcks
+ * @param {object[]|null} [effectiveRules] rules actually in force (e.g. manifest rules); defaults to config.rules
+ */
+export function analyzeContractSmells(
+  config,
+  coverage = null,
+  ackState = { exists: false, acks: [] },
+  effectiveRules = null
+) {
+  const layers = Array.isArray(config?.layers) ? config.layers : [];
+  const rules = wellFormedRules(config, effectiveRules);
+  const layerByName = new Map();
+  for (const l of layers) {
+    if (l && typeof l.name === 'string') layerByName.set(l.name, l);
+  }
+  const filesPerLayer = new Map();
+  for (const row of coverage?.layers ?? []) {
+    if (row && typeof row.name === 'string') filesPerLayer.set(row.name, row.files ?? 0);
+  }
+
+  const explicitAllows = rules.filter((r) => r.allowed === true && r.from !== r.to);
+
+  /** Per-id findings: { edge (canonical, for acks; null = unmatchable), detail (display) }. */
+  const findings = {};
+  const add = (id, edge, detail) => {
+    (findings[id] ??= []).push({ edge, detail });
+  };
+
+  // 1) Explicitly bidirectional allowed edges (permits future cycles by declaration).
+  const allowKeys = new Set(explicitAllows.map((r) => directedKey(r.from, r.to)));
+  const seenPairs = new Set();
+  for (const r of explicitAllows) {
+    if (!allowKeys.has(directedKey(r.to, r.from))) continue;
+    const key = directedKey(...[r.from, r.to].sort());
+    if (seenPairs.has(key)) continue;
+    seenPairs.add(key);
+    const label = pairLabel(r.from, r.to);
+    add(
+      'contract-bidirectional-allow',
+      ackMatchable(r.from, r.to) ? label : null,
+      `edge:${label}`
+    );
+  }
+
+  // 2) Peripheral layers explicitly allowed into orchestration/persistence cores.
+  for (const r of explicitAllows) {
+    if (PERIPHERAL_LAYER_RE.test(r.from) && CORE_TARGET_RE.test(r.to)) {
+      add(
+        'contract-peripheral-depends-core',
+        ackMatchable(r.from, r.to) ? `${r.from}->${r.to}` : null,
+        `edge:${r.from}->${r.to}`
+      );
+    }
+  }
+
+  // 3) Lateral adapter-to-adapter explicit allows. Skip only edges the peripheral
+  //    sensor already flagged (peripheral source AND core-ish target).
+  for (const r of explicitAllows) {
+    if (PERIPHERAL_LAYER_RE.test(r.from) && CORE_TARGET_RE.test(r.to)) continue;
+    if (ADAPTER_LAYER_RE.test(r.from) && ADAPTER_LAYER_RE.test(r.to)) {
+      add(
+        'contract-lateral-adapter-allow',
+        ackMatchable(r.from, r.to) ? `${r.from}->${r.to}` : null,
+        `edge:${r.from}->${r.to}`
+      );
+    }
+  }
+
+  // 4) Dead rules: self edges (the gate ignores same-layer rules), unknown layers,
+  //    or — when coverage is known — layers matching zero files (optional layers exempt).
+  for (const r of rules) {
+    const edge = `${r.from}->${r.to}`;
+    const ackEdge = ackMatchable(r.from, r.to) ? edge : null;
+    if (r.from === r.to) {
+      add('contract-dead-rule', ackEdge, `rule:${edge} (self edge has no effect)`);
+      continue;
+    }
+    for (const side of [r.from, r.to]) {
+      if (side.length === 0) continue;
+      const layer = layerByName.get(side);
+      if (!layer) {
+        add('contract-dead-rule', ackEdge, `rule:${edge} (unknown layer: ${side})`);
+      } else if (filesPerLayer.get(side) === 0 && layer.optional !== true) {
+        add('contract-dead-rule', ackEdge, `rule:${edge} (empty layer: ${side})`);
+      }
+    }
+  }
+
+  const smells = [];
+  let matchedAcks = 0;
+  for (const id of CONTRACT_SMELL_IDS) {
+    const entries = findings[id];
+    if (!entries || entries.length === 0) continue;
+    const kept = [];
+    let acknowledgedEdges = 0;
+    const seenDetail = new Set();
+    for (const entry of entries) {
+      if (seenDetail.has(entry.detail)) continue;
+      seenDetail.add(entry.detail);
+      if (isAcknowledged(ackState, id, entry.edge)) {
+        acknowledgedEdges += 1;
+        continue;
+      }
+      kept.push(entry);
+    }
+    matchedAcks += acknowledgedEdges;
+    // Fully acknowledged ids emit no smell; the summary reports applied acks.
+    if (kept.length === 0) continue;
+    // Deterministic output independent of rule declaration order.
+    kept.sort((a, b) => (a.detail < b.detail ? -1 : a.detail > b.detail ? 1 : 0));
+    const evidence = kept.slice(0, MAX_EVIDENCE).map((e) => e.detail);
+    if (kept.length > MAX_EVIDENCE) evidence.push(`…(+${kept.length - MAX_EVIDENCE} more)`);
+    smells.push({
+      id,
+      severity: 'warn',
+      message: messageFor(id, kept),
+      outcome: CONTRACT_SMELL_OUTCOMES[id],
+      evidence,
+      fix: fixFor(id),
+      acknowledgedEdges,
+    });
+  }
+  return { smells, matchedAcks };
+}
+
+/**
+ * Detect contract smells (compat wrapper over analyzeContractSmells).
+ * @returns {Array<{id: string, severity: 'warn', message: string, outcome: string, evidence: string[], fix: string, acknowledgedEdges: number}>}
+ */
+export function detectContractSmells(
+  config,
+  coverage = null,
+  ackState = { exists: false, acks: [] },
+  effectiveRules = null
+) {
+  return analyzeContractSmells(config, coverage, ackState, effectiveRules).smells;
+}
+
+function messageFor(id, entries) {
+  const shown = entries.slice(0, MAX_MESSAGE_EDGES).map((e) => e.detail.replace(/^(edge|rule):/, ''));
+  const more = entries.length > shown.length ? `, …(+${entries.length - shown.length} more)` : '';
+  const list = `${shown.join(', ')}${more}`;
+  switch (id) {
+    case 'contract-bidirectional-allow':
+      return `Both directions are explicitly allowed between ${entries.length} pair(s): ${list}. No cycle exists yet, but the contract permits one by declaration.`;
+    case 'contract-peripheral-depends-core':
+      return `Peripheral (audit/observability) layers are explicitly allowed into core layers (${entries.length} edge(s)): ${list}. Observability stops being fully peripheral.`;
+    case 'contract-lateral-adapter-allow':
+      return `Adapter layers are explicitly allowed to import sibling adapter layers (${entries.length} edge(s)): ${list}. Shared mappers/aliases tend to accumulate on this edge.`;
+    case 'contract-dead-rule':
+      return `${entries.length} rule(s) enforce nothing: ${list}.`;
+    default:
+      return `Contract smell on: ${list}.`;
+  }
+}
+
+function fixFor(id) {
+  switch (id) {
+    case 'contract-bidirectional-allow':
+      return `Keep one direction (edit via /ark-contract), or record the deliberate loop in ${CONTRACT_SMELL_ACKS_PATH} with a reason.`;
+    case 'contract-peripheral-depends-core':
+      return `Invert the edge: core emits events/ports the peripheral layer consumes (/ark-contract), or acknowledge with a reason in ${CONTRACT_SMELL_ACKS_PATH}.`;
+    case 'contract-lateral-adapter-allow':
+      return `Move shared shapes into Domain/shared kernel and drop the lateral allow (/ark-contract), or acknowledge with a reason in ${CONTRACT_SMELL_ACKS_PATH}.`;
+    case 'contract-dead-rule':
+      return 'Fix the layer patterns so the layer matches real files, or delete the stale/self rule via /ark-contract.';
+    default:
+      return 'Review the contract edge via /ark-contract; never weaken the gate to silence a smell.';
+  }
+}
+
+/**
+ * W02 — fixed comparative wording per band. Facts + a note; explicitly never a
+ * score, ranking, or gate input. Heavy wording must never suggest deleting layers.
+ */
+export const GOVERNANCE_WEIGHT_NOTES = Object.freeze({
+  heavy:
+    'Heavier than typical for the governed tree size. Not a defect and not a score — but before adding another layer or rule, ask for demonstrated pressure (repeated violations or acknowledgments on one edge). Do not delete working layers to change this number.',
+  light:
+    'Lighter than typical for the governed tree size — a large tree with few boundaries. Consider whether a new boundary is justified where violations or churn concentrate.',
+  typical: 'Within the typical band for the governed tree size.',
+  unknown: 'Not enough governed files (or declared layers) to describe governance weight.',
+});
+
+/**
+ * Fixed banding thresholds (stated in docs/package-surface.md; deterministic, not tunables).
+ * heavy: fewer than 25 governed files per layer AND (6+ layers OR 4+ rules per layer) —
+ * both signals are size-relative, so a large tree with a dense but proportionate rule
+ * matrix never reads heavy. light: at most 2 layers over 150+ governed files.
+ */
+const HEAVY_FILES_PER_LAYER_BELOW = 25;
+const HEAVY_MIN_LAYERS = 6;
+const HEAVY_RULES_PER_LAYER = 4;
+const LIGHT_MAX_LAYERS = 2;
+const LIGHT_MIN_FILES = 150;
+
+/** Rules in force, filtered to well-formed entries (string from/to, boolean allowed). */
+function wellFormedRules(config, effectiveRules) {
+  const rules = (Array.isArray(effectiveRules) ? effectiveRules : config?.rules) ?? [];
+  return rules.filter(
+    (r) =>
+      r !== null &&
+      typeof r === 'object' &&
+      typeof r.from === 'string' &&
+      typeof r.to === 'string' &&
+      typeof r.allowed === 'boolean'
+  );
+}
+
+/**
+ * W02 — descriptive governance-weight facts for a contract over a governed tree.
+ * Raw counts and ratios with a fixed comparative note. Advisory only.
+ *
+ * @param {object} config ark.config (layers; rules unless overridden)
+ * @param {object|null} coverage computeCoverage result
+ * @param {object[]|null} [effectiveRules]
+ */
+export function computeGovernanceWeight(config, coverage = null, effectiveRules = null) {
+  const layers = Array.isArray(config?.layers) ? config.layers : [];
+  const rules = wellFormedRules(config, effectiveRules);
+  const declaredLayers = layers.filter((l) => l && typeof l.name === 'string').length;
+  const governedFiles = coverage?.governed?.classifiedFiles ?? 0;
+  const populatedLayers = (coverage?.layers ?? []).filter((r) => r && (r.files ?? 0) > 0).length;
+  const deniedEdges = rules.filter((r) => r.allowed === false).length;
+  const allowedEdges = rules.filter((r) => r.allowed === true).length;
+  const round1 = (n) => Math.round(n * 10) / 10;
+  const base = {
+    declaredLayers,
+    populatedLayers,
+    governedFiles,
+    rules: rules.length,
+    deniedEdges,
+    allowedEdges,
+    notAScore: true,
+  };
+  if (declaredLayers === 0 || !(Number.isFinite(governedFiles) && governedFiles > 0)) {
+    return {
+      ...base,
+      governedFiles: Number.isFinite(governedFiles) ? governedFiles : 0,
+      filesPerLayer: null,
+      rulesPerLayer: null,
+      weight: 'unknown',
+      note: GOVERNANCE_WEIGHT_NOTES.unknown,
+    };
+  }
+  // Band on the raw ratios; the rounded values are for display only.
+  const rawFilesPerLayer = governedFiles / declaredLayers;
+  const rawRulesPerLayer = rules.length / declaredLayers;
+  let weight = 'typical';
+  if (
+    rawFilesPerLayer < HEAVY_FILES_PER_LAYER_BELOW &&
+    (declaredLayers >= HEAVY_MIN_LAYERS || rawRulesPerLayer >= HEAVY_RULES_PER_LAYER)
+  ) {
+    weight = 'heavy';
+  } else if (declaredLayers <= LIGHT_MAX_LAYERS && governedFiles >= LIGHT_MIN_FILES) {
+    weight = 'light';
+  }
+  return {
+    ...base,
+    filesPerLayer: round1(rawFilesPerLayer),
+    rulesPerLayer: round1(rawRulesPerLayer),
+    weight,
+    note: GOVERNANCE_WEIGHT_NOTES[weight],
+  };
+}
+
+/**
+ * One-call compute for doctor: acks + smells + governance weight + JSON-ready summary.
+ * `rules` should be the rules actually in force (manifest-aware callers pass them).
+ *
+ * @param {string} root
+ * @param {object} config
+ * @param {object|null} coverage
+ * @param {object[]|null} [rules]
+ */
+export function computeContractHealth(root, config, coverage, rules = null) {
+  const ackState = loadContractSmellAcks(root);
+  const { smells, matchedAcks } = analyzeContractSmells(config, coverage, ackState, rules);
+  return {
+    ...summarizeContractHealth(smells, ackState, matchedAcks),
+    governanceWeight: computeGovernanceWeight(config, coverage, rules),
+    smells,
+  };
+}
+
+/**
+ * Print the human doctor section (advisory). No output when there is nothing to say.
+ * @param {ReturnType<typeof computeContractHealth>} health
+ * @param {{ line: (mark: string, text: string) => void, warn: string, color: { bold: (s: string) => string, dim: (s: string) => string } }} io
+ */
+export function printContractHealthSection(health, io) {
+  const rows = formatContractHealthLines(health?.smells ?? [], health);
+  if (rows.length === 0) return;
+  console.log('');
+  console.log(io.color.bold('Contract health (advisory)'));
+  for (const row of rows) {
+    io.line(row.mark === 'warn' ? io.warn : ' ', row.mark === 'dim' ? io.color.dim(row.text) : row.text);
+  }
+}
+
+/**
+ * Human doctor lines for the contract-health section (advisory).
+ * Returns `{ mark, text }` rows with mark `'warn' | 'dim'`; doctor prints them.
+ * Empty array when there is nothing to say: no smells, a valid/absent ack file,
+ * and a non-noteworthy governance weight (only `heavy`/`light` print).
+ *
+ * @param {ReturnType<typeof detectContractSmells>} smells
+ * @param {ReturnType<typeof computeContractHealth>} health also read: `health.governanceWeight`
+ */
+export function formatContractHealthLines(smells, health) {
+  const rows = [];
+  const list = smells ?? [];
+  const gw = health?.governanceWeight;
+  const weightNoteworthy = gw?.weight === 'heavy' || gw?.weight === 'light';
+  if (list.length === 0 && !health?.ackFile?.invalid && !weightNoteworthy) return rows;
+  if (health?.ackFile?.invalid) {
+    rows.push({
+      mark: 'warn',
+      text: `${health.ackFile.path} is present but invalid — acknowledgments are ignored, not silently applied.`,
+    });
+  }
+  for (const smell of list.slice(0, 5)) {
+    rows.push({ mark: 'warn', text: `[${smell.id}] ${smell.outcome}` });
+    rows.push({ mark: 'dim', text: `detail: ${smell.message}` });
+    if (smell.evidence?.length) {
+      const shown = smell.evidence.slice(0, 4);
+      const more = smell.evidence.length > 4 ? ` …(+${smell.evidence.length - 4} more)` : '';
+      rows.push({ mark: 'dim', text: `evidence: ${shown.join(', ')}${more}` });
+    }
+    rows.push({ mark: 'dim', text: `fix: ${smell.fix}` });
+  }
+  if (list.length > 5) {
+    rows.push({ mark: 'dim', text: `…(+${list.length - 5} more contract smell(s) in doctor JSON)` });
+  }
+  if ((health?.acknowledged ?? 0) > 0) {
+    rows.push({ mark: 'dim', text: `acknowledged edges applied: ${health.acknowledged}` });
+  }
+  if (weightNoteworthy) {
+    rows.push({
+      mark: 'warn',
+      text: `governance weight: ${gw.weight} — ${gw.declaredLayers} layer(s), ${gw.rules} rule(s), ${gw.governedFiles} governed file(s) (${gw.filesPerLayer} files/layer)`,
+    });
+    rows.push({ mark: 'dim', text: gw.note });
+  }
+  rows.push({
+    mark: 'dim',
+    text: 'advisory only — the gate verdict and design fitness are unchanged',
+  });
+  return rows;
+}
+
+/**
+ * Contract-health summary for doctor JSON / human output. Advisory only.
+ * `acknowledged` counts ack entries that MATCHED a detected edge (stale acks count 0).
+ *
+ * @param {ReturnType<typeof detectContractSmells>} smells
+ * @param {ReturnType<typeof loadContractSmellAcks>} ackState
+ * @param {number} [matchedAcks]
+ */
+export function summarizeContractHealth(smells, ackState = { exists: false, acks: [] }, matchedAcks = 0) {
+  const list = Array.isArray(smells) ? smells : [];
+  return {
+    status: list.length > 0 ? 'contract-smells' : 'ok',
+    smellCount: list.length,
+    ids: list.map((s) => s.id),
+    acknowledged: ackState?.invalid ? 0 : matchedAcks,
+    advisory: true,
+    label:
+      list.length > 0
+        ? `Contract health: ${list.length} contract smell(s) — advisory; the gate verdict is unchanged`
+        : 'Contract health: no contract smells detected',
+    ackFile: {
+      path: ackState?.path ?? CONTRACT_SMELL_ACKS_PATH,
+      present: ackState?.exists === true,
+      invalid: ackState?.invalid === true,
+      ...(ackState?.invalid ? { error: ackState.error ?? 'invalid' } : {}),
+    },
+  };
+}