arkgate 3.4.0 → 3.6.0

package/CHANGELOG.md

@@ -4,6 +4,77 @@ All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are do
 
 ## Unreleased
 
+## 3.6.0 — 2026-07-17
+
+Phase X closes: the doctor learns to see **physical shape** and agents get a governed way to
+execute reorganizations, plus three field warm-ups from the 3.5.0 the field adopter validation.
+Everything remains **advisory** — no verdict, exit-code, `designFitness`, or `patternBets`
+change. **No breaking** CLI or `ark.config.json` changes. **No gate weaken. No apply path.**
+
+### Added
+
+- **Physical cohesion sensor (X04, ADR 0010):** `doctor.physicalCohesion` reports domain
+  concepts exploded across mirrored directory clusters — concentration, not volume (dispersed
+  `use-*` hooks never fire). Deterministic path/name tokenization (framework filenames take the
+  topmost meaningful path segment; monorepo scaffold roots are never a concept); fixed
+  corpus-calibrated thresholds (`maxCluster ≥ 40` OR ≥2 anchors ≥ 20); findings ranked and
+  capped honestly; anchors under `app/`/`pages/` are `fixedByConvention`. `notAScore` — facts,
+  never a score or gate input.
+- **Reshape pilot (X04):** `physicalCohesion.reshapePilot.nextPilot` is a **proposed, never
+  applied** card — one at a time, smallest convention-free anchor, `moveSample`/`movesTotal`,
+  `successSignal`, `killSwitch`, hard `doNot[]`. Real moves run only through the write gate and
+  atomic preflight via `/ark-loop`; merges are `/ark-architect` **merge cards** (domain
+  modeling, **never a codemod**); `/ark-fix` never folds reshapes into a fix batch. The
+  consolidation target subtree is never re-proposed as a source — the loop converges (validated
+  end to end: pilot → gate → kill switch → judgment → convergence).
+- **Stale acknowledgments (X05):** ack entries matching no detected edge (orphaned, unknown id,
+  typo) land in `contractHealth.ackLifecycle` as `staleCount` + `stale[]` (sorted, capped);
+  doctor and report name the exact entries to fix or delete, even at zero visible smells.
+
+### Changed
+
+- **Mid-name families (X06):** the family-infra carve-out matches the target's family token
+  against ANY source token (`HoursPersistenceAdapters -> PersistenceInfrastructure` goes
+  quiet); generic role words (`adapter(s)`/`gateway(s)`) never count as a family, so
+  `AdaptersCore` is not every `*Adapters` layer's base.
+- **Report evidence overflow (X07):** per-finding evidence lists announce their 6-item cap with
+  an honest `(+N more)` marker; expired/stale lifecycle notes carry the same honesty.
+
+## 3.5.0 — 2026-07-16
+
+Field-feedback release (Phase X, from an internal field-adoption session): the HTML report reaches
+parity with the doctor and stays there by an executable rule, contract-smell acknowledgments gain
+a lifecycle so migration acks cannot fossilize, and the lateral-adapter smell stops firing on a
+family's own infrastructure base. Everything remains **advisory** — no verdict, `designFitness`,
+or gate behavior changes. **No breaking** CLI or `ark.config.json` changes. **No gate weaken.**
+
+### Added
+
+- **Report parity (X01):** `ark-check --report` now renders every doctor advisory — contract
+  health (smells with evidence/fix, acknowledgment honesty, invalid-sidecar warning), governance
+  weight, ambient state (idle/clean/findings with honest overflow), and capability-wall badges
+  (`pure` / `walls: …`) in the layers table. The rule is **executable**: `reportParity.test.ts`
+  enumerates the advisory keys `computeDoctorAdvisories` returns and fails CI when any key lacks
+  a `data-advisory` section — the report can never silently fall behind the product again.
+- **Acknowledgment lifecycle (X02):** a contract-smell ack may carry an optional `reviewBy`
+  (`YYYY-MM-DD`, strict round-trip validation). Past that date the ack **stops applying** and the
+  smell returns with `(ack expired …)` annotated evidence; a re-ack with a fresh date wins over a
+  dead entry, and once any dated ack exists for an edge the dated entries govern — a leftover
+  undated duplicate cannot resurrect an expired exception.
+  Undated acks keep applying (backward compatible) but are counted and surfaced —
+  doctor line, report note — even when every smell is suppressed. Malformed dates never apply
+  (fail-loud, like a sloppy edge); non-string `reviewBy` invalidates the file. Doctor JSON gains
+  `contractHealth.ackLifecycle` (`{ undated, malformed, expiredCount, expired[] }`).
+
+### Changed
+
+- **Lateral-adapter smell (X03):** `contract-lateral-adapter-allow` no longer fires when an
+  adapter layer reaches its **own family's infra base** (same leading name token and every
+  remaining target token an infra word — `Infra`/`Base`/`Core`/`Shared`/`Common`/`Kernel`/
+  `Platform`/`Foundation` — e.g. `PaymentsAdapters -> PaymentsInfra`; `PaymentsCoreAdapters` is
+  still a sibling). Cross-family edges, same-family non-infra siblings, and the reverse
+  direction (base → member) still fire.
+
 ## 3.4.0 — 2026-07-16
 
 Understandable execution, second slice (Phase U: U04–U07): the capability evidence shipped in

package/bin/ark-check.mjs

@@ -59,6 +59,7 @@ import {
   reportsDir,
   readJsonSafe,
 } from './lib/html-report.mjs';
+import { computeDoctorAdvisories } from './lib/doctor-advisories.mjs';
 import { buildReportDepthPayload } from './lib/html-report-depth.mjs';
 import { shouldOpenHtmlReport, openHtmlInBrowser } from './lib/open-html.mjs';
 import {
@@ -101,7 +102,6 @@ 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) {
   const args = {
     root: process.cwd(),
@@ -1320,6 +1320,7 @@ async function main() {
       originJustCreated: !existingOrigin,
       adoption: adoptionForReport,
       designDepth,
+      advisories: computeDoctorAdvisories(root, config, coverage, rules, files, ts),
     };
     const html = args.beginner
       ? renderBeginnerHtmlReport(reportPayload)

package/bin/lib/contract-smells.mjs

@@ -11,6 +11,12 @@
  * 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.
  *
+ * X02 — acks have a lifecycle: an optional `reviewBy` (YYYY-MM-DD) marks when a
+ * deliberate exception must be re-reviewed. Past that date the ack stops
+ * applying and the smell returns annotated — migration acks cannot fossilize.
+ * Undated acks keep applying (backward compatible) but are counted and
+ * reported so they can be given a date.
+ *
  * 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.
@@ -49,6 +55,36 @@ 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;
+const FAMILY_INFRA_RE = /^(infra(structure)?|base|core|shared|common|kernel|platform|foundation)$/i;
+
+/** Split a layer name into words: camelCase boundaries, digits, delimiters. */
+function nameTokens(name) {
+  return String(name).match(/[A-Z]?[a-z]+|[A-Z]+(?![a-z])|\d+/g) ?? [];
+}
+
+/**
+ * X03/X06 — an adapter reaching its OWN family's infrastructure base is not a
+ * lateral peer: the target reads as `<Family><InfraWords…>` and the source
+ * carries the family token ANYWHERE in its name (X06, field corpus names
+ * domain-scoped adapters `HoursPersistenceAdapters` over
+ * `PersistenceInfrastructure` — the family sits mid-name). EVERY remaining
+ * target token must be an infra word (Infra/Base/Core/Shared/…) —
+ * `PaymentsCoreAdapters` is still a sibling, not a base. The reverse
+ * direction (base → member) never matches: the target must BE the base.
+ * Name heuristic like the role regexes above — a miss costs a warning line.
+ */
+function isFamilyInfrastructureEdge(from, to) {
+  const fromTokens = nameTokens(from);
+  const toTokens = nameTokens(to);
+  if (fromTokens.length === 0 || toTokens.length < 2) return false;
+  const family = toTokens[0].toLowerCase();
+  // A generic role word is not a family: `AdaptersCore` must not read as the
+  // "Adapters family" base for every *Adapters layer — that would silently
+  // quiet genuine cross-family edges. (`Persistence` stays a valid family.)
+  if (/^(adapters?|gateways?)$/.test(family)) return false;
+  if (family.length < 2 || !fromTokens.some((t) => t.toLowerCase() === family)) return false;
+  return toTokens.slice(1).every((t) => FAMILY_INFRA_RE.test(t));
+}
 
 /** Collision-safe internal key for a directed edge (layer names are arbitrary strings). */
 function directedKey(from, to) {
@@ -100,9 +136,12 @@ export function loadContractSmellAcks(root) {
       typeof a === 'object' &&
       typeof a.id === 'string' &&
       typeof a.edge === 'string' &&
-      a.edge.trim().length > 0
+      a.edge.trim().length > 0 &&
+      (a.reviewBy === undefined || typeof a.reviewBy === 'string')
   );
-  if (!wellFormed) return invalid('every ack needs string id and non-empty string edge');
+  if (!wellFormed) {
+    return invalid('every ack needs string id, non-empty string edge, and string reviewBy when present');
+  }
   return { path: relPath, exists: true, acks };
 }
 
@@ -121,10 +160,44 @@ function normalizeAckEdge(id, edge) {
   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);
+/**
+ * X02 — lifecycle status of one ack entry. `undated` and `current` apply
+ * (suppress); `expired` and `malformed` do not — fail-loud like a sloppy edge.
+ * Strict round-trip date check: `2026-02-30` must not pass as valid.
+ */
+function ackLifecycleStatus(ack, today) {
+  const rb = ack.reviewBy;
+  if (rb === undefined || rb === null) return 'undated';
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(rb)) return 'malformed';
+  const parsed = new Date(`${rb}T00:00:00.000Z`);
+  if (Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== rb) {
+    return 'malformed';
+  }
+  return typeof today === 'string' && rb < today ? 'expired' : 'current';
+}
+
+/**
+ * Match a detected edge against the ack sidecar with lifecycle applied.
+ * Returns how the edge resolves: `none` (no matching ack), an applying status
+ * (`current` | `undated`), or a non-applying one (`expired` | `malformed`,
+ * with the reviewBy that failed). Once ANY dated ack exists for the edge, the
+ * dated entries govern — a leftover undated duplicate cannot resurrect an
+ * expired exception. Among dated entries a fresh re-ack wins over a dead one.
+ */
+function resolveAck(ackState, id, canonicalEdge, today) {
+  if (!ackState || ackState.invalid || !Array.isArray(ackState.acks)) return { status: 'none' };
+  if (canonicalEdge == null) return { status: 'none' };
+  let dead = null;
+  let undated = false;
+  for (const a of ackState.acks) {
+    if (a.id !== id || normalizeAckEdge(id, a.edge) !== canonicalEdge) continue;
+    const status = ackLifecycleStatus(a, today);
+    if (status === 'current') return { status };
+    if (status === 'undated') undated = true;
+    else dead ??= { status, reviewBy: a.reviewBy };
+  }
+  if (dead) return dead;
+  return undated ? { status: 'undated' } : { status: 'none' };
 }
 
 /**
@@ -140,7 +213,8 @@ export function analyzeContractSmells(
   config,
   coverage = null,
   ackState = { exists: false, acks: [] },
-  effectiveRules = null
+  effectiveRules = null,
+  today = null
 ) {
   const layers = Array.isArray(config?.layers) ? config.layers : [];
   const rules = wellFormedRules(config, effectiveRules);
@@ -188,10 +262,12 @@ export function analyzeContractSmells(
     }
   }
 
-  // 3) Lateral adapter-to-adapter explicit allows. Skip only edges the peripheral
-  //    sensor already flagged (peripheral source AND core-ish target).
+  // 3) Lateral adapter-to-adapter explicit allows. Skip edges the peripheral
+  //    sensor already flagged (peripheral source AND core-ish target), and
+  //    X03: an adapter reaching its own family's infra base is not a peer.
   for (const r of explicitAllows) {
     if (PERIPHERAL_LAYER_RE.test(r.from) && CORE_TARGET_RE.test(r.to)) continue;
+    if (isFamilyInfrastructureEdge(r.from, r.to)) continue;
     if (ADAPTER_LAYER_RE.test(r.from) && ADAPTER_LAYER_RE.test(r.to)) {
       add(
         'contract-lateral-adapter-allow',
@@ -221,8 +297,28 @@ export function analyzeContractSmells(
     }
   }
 
+  // X05 — an ack that matches no detected edge is stale: orphaned by a fixed
+  // contract, a quieted heuristic, or a typo. Detected BEFORE ack filtering.
+  const detectedEdges = new Map();
+  for (const [id, entries] of Object.entries(findings)) {
+    detectedEdges.set(id, new Set(entries.map((e) => e.edge).filter((e) => e != null)));
+  }
+  const staleEdges = [];
+  if (ackState && !ackState.invalid && Array.isArray(ackState.acks)) {
+    for (const a of ackState.acks) {
+      const canonical = normalizeAckEdge(a.id, a.edge);
+      if (canonical != null && detectedEdges.get(a.id)?.has(canonical)) continue;
+      staleEdges.push({ id: a.id, edge: a.edge });
+    }
+    // Stable under sidecar reordering, like every other output here.
+    staleEdges.sort((a, b) =>
+      a.id === b.id ? (a.edge < b.edge ? -1 : a.edge > b.edge ? 1 : 0) : a.id < b.id ? -1 : 1
+    );
+  }
+
   const smells = [];
   let matchedAcks = 0;
+  const ackLifecycle = { undated: 0, malformed: 0, expired: [], stale: staleEdges };
   for (const id of CONTRACT_SMELL_IDS) {
     const entries = findings[id];
     if (!entries || entries.length === 0) continue;
@@ -232,8 +328,20 @@ export function analyzeContractSmells(
     for (const entry of entries) {
       if (seenDetail.has(entry.detail)) continue;
       seenDetail.add(entry.detail);
-      if (isAcknowledged(ackState, id, entry.edge)) {
+      const ack = resolveAck(ackState, id, entry.edge, today);
+      if (ack.status === 'current' || ack.status === 'undated') {
         acknowledgedEdges += 1;
+        if (ack.status === 'undated') ackLifecycle.undated += 1;
+        continue;
+      }
+      if (ack.status === 'expired') {
+        ackLifecycle.expired.push({ id, edge: entry.edge, reviewBy: ack.reviewBy });
+        kept.push({ ...entry, detail: `${entry.detail} (ack expired ${ack.reviewBy})` });
+        continue;
+      }
+      if (ack.status === 'malformed') {
+        ackLifecycle.malformed += 1;
+        kept.push({ ...entry, detail: `${entry.detail} (ack review-by malformed)` });
         continue;
       }
       kept.push(entry);
@@ -255,20 +363,23 @@ export function analyzeContractSmells(
       acknowledgedEdges,
     });
   }
-  return { smells, matchedAcks };
+  return { smells, matchedAcks, ackLifecycle };
 }
 
 /**
  * Detect contract smells (compat wrapper over analyzeContractSmells).
+ * Defaults `today` to the real clock so expired acks stop applying on every
+ * public path, not only through the doctor; pass `null` to disable expiry.
  * @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
+  effectiveRules = null,
+  today = todayUtc()
 ) {
-  return analyzeContractSmells(config, coverage, ackState, effectiveRules).smells;
+  return analyzeContractSmells(config, coverage, ackState, effectiveRules, today).smells;
 }
 
 function messageFor(id, entries) {
@@ -399,6 +510,11 @@ export function computeGovernanceWeight(config, coverage = null, effectiveRules
   };
 }
 
+/** Today as UTC YYYY-MM-DD — the only clock read; tests inject `today` instead. */
+function todayUtc() {
+  return new Date().toISOString().slice(0, 10);
+}
+
 /**
  * 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).
@@ -407,12 +523,19 @@ export function computeGovernanceWeight(config, coverage = null, effectiveRules
  * @param {object} config
  * @param {object|null} coverage
  * @param {object[]|null} [rules]
+ * @param {string} [today] UTC YYYY-MM-DD for ack lifecycle; defaults to the real clock
  */
-export function computeContractHealth(root, config, coverage, rules = null) {
+export function computeContractHealth(root, config, coverage, rules = null, today = todayUtc()) {
   const ackState = loadContractSmellAcks(root);
-  const { smells, matchedAcks } = analyzeContractSmells(config, coverage, ackState, rules);
+  const { smells, matchedAcks, ackLifecycle } = analyzeContractSmells(
+    config,
+    coverage,
+    ackState,
+    rules,
+    today
+  );
   return {
-    ...summarizeContractHealth(smells, ackState, matchedAcks),
+    ...summarizeContractHealth(smells, ackState, matchedAcks, ackLifecycle),
     governanceWeight: computeGovernanceWeight(config, coverage, rules),
     smells,
   };
@@ -447,7 +570,13 @@ export function formatContractHealthLines(smells, health) {
   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;
+  const lc = health?.ackLifecycle;
+  // Undated and stale acks must surface even when every smell is suppressed —
+  // fossilization (X02) and orphaned entries (X05) hide exactly there.
+  const lifecycleNoteworthy = (lc?.undated ?? 0) > 0 || (lc?.staleCount ?? 0) > 0;
+  if (list.length === 0 && !health?.ackFile?.invalid && !weightNoteworthy && !lifecycleNoteworthy) {
+    return rows;
+  }
   if (health?.ackFile?.invalid) {
     rows.push({
       mark: 'warn',
@@ -470,6 +599,32 @@ export function formatContractHealthLines(smells, health) {
   if ((health?.acknowledged ?? 0) > 0) {
     rows.push({ mark: 'dim', text: `acknowledged edges applied: ${health.acknowledged}` });
   }
+  if ((lc?.expiredCount ?? 0) > 0) {
+    rows.push({
+      mark: 'warn',
+      text: `${lc.expiredCount} acknowledgment(s) past review-by — the smell is active again; re-review the edge and re-ack with a new date, or fix the contract.`,
+    });
+  }
+  if ((lc?.malformed ?? 0) > 0) {
+    rows.push({
+      mark: 'warn',
+      text: `${lc.malformed} acknowledgment(s) have a malformed review-by (expected YYYY-MM-DD) — they are ignored, not silently applied.`,
+    });
+  }
+  if ((lc?.undated ?? 0) > 0) {
+    rows.push({
+      mark: 'dim',
+      text: `${lc.undated} applied acknowledgment(s) have no review-by date — add one so migration acks cannot fossilize.`,
+    });
+  }
+  if ((lc?.staleCount ?? 0) > 0) {
+    const shown = (lc.stale ?? []).slice(0, 4).map((s) => s.edge);
+    const more = lc.staleCount > shown.length ? ` …(+${lc.staleCount - shown.length} more)` : '';
+    rows.push({
+      mark: 'dim',
+      text: `${lc.staleCount} acknowledgment(s) match no detected edge — stale; fix the edge string or delete the entry: ${shown.join(', ')}${more}`,
+    });
+  }
   if (weightNoteworthy) {
     rows.push({
       mark: 'warn',
@@ -487,18 +642,38 @@ export function formatContractHealthLines(smells, health) {
 /**
  * Contract-health summary for doctor JSON / human output. Advisory only.
  * `acknowledged` counts ack entries that MATCHED a detected edge (stale acks count 0).
+ * X02 — `ackLifecycle` reports how applied acks age: `undated` applied without
+ * a review-by, `expired` past it (no longer applied), `malformed` bad dates.
+ * X05 — `stale` counts ack entries matching NO detected edge (orphaned or
+ * typo'd); they suppress nothing and should be fixed or deleted.
  *
  * @param {ReturnType<typeof detectContractSmells>} smells
  * @param {ReturnType<typeof loadContractSmellAcks>} ackState
  * @param {number} [matchedAcks]
+ * @param {{ undated: number, malformed: number, expired: Array<{id: string, edge: string, reviewBy: string}>, stale: Array<{id: string, edge: string}> }} [ackLifecycle]
  */
-export function summarizeContractHealth(smells, ackState = { exists: false, acks: [] }, matchedAcks = 0) {
+export function summarizeContractHealth(
+  smells,
+  ackState = { exists: false, acks: [] },
+  matchedAcks = 0,
+  ackLifecycle = { undated: 0, malformed: 0, expired: [], stale: [] }
+) {
   const list = Array.isArray(smells) ? smells : [];
+  const expired = Array.isArray(ackLifecycle?.expired) ? ackLifecycle.expired : [];
+  const stale = Array.isArray(ackLifecycle?.stale) ? ackLifecycle.stale : [];
   return {
     status: list.length > 0 ? 'contract-smells' : 'ok',
     smellCount: list.length,
     ids: list.map((s) => s.id),
     acknowledged: ackState?.invalid ? 0 : matchedAcks,
+    ackLifecycle: {
+      undated: ackLifecycle?.undated ?? 0,
+      malformed: ackLifecycle?.malformed ?? 0,
+      expiredCount: expired.length,
+      expired: expired.slice(0, MAX_EVIDENCE),
+      staleCount: stale.length,
+      stale: stale.slice(0, MAX_EVIDENCE),
+    },
     advisory: true,
     label:
       list.length > 0

package/bin/lib/doctor-advisories.mjs

@@ -1,20 +1,33 @@
 /**
  * Doctor's advisory sensors, aggregated (W01 contract health + U05 ambient
- * state). Advisory only: nothing here feeds a verdict, designFitness, or an
- * exit code. One seam keeps doctor-plan.mjs inside its module budget as new
- * advisory surfaces land.
+ * state + X04 physical cohesion). Advisory only: nothing here feeds a
+ * verdict, designFitness, or an exit code. One seam keeps doctor-plan.mjs
+ * inside its module budget as new advisory surfaces land.
  */
 import { computeAmbientState, printAmbientStateSection } from './ambient-state.mjs';
 import { computeContractHealth, printContractHealthSection } from './contract-smells.mjs';
+import {
+  computePhysicalCohesion,
+  computeReshapePilot,
+  printPhysicalCohesionSection,
+} from './physical-cohesion.mjs';
 
 export function computeDoctorAdvisories(root, config, cov, rules, files, ts) {
+  const physicalCohesion = computePhysicalCohesion(root, files);
+  physicalCohesion.reshapePilot = computeReshapePilot(physicalCohesion, files, root);
   return {
     contractHealth: computeContractHealth(root, config, cov, rules),
     ambientState: computeAmbientState(ts, root, config, files),
+    physicalCohesion,
   };
 }
 
 export function printDoctorAdvisories(advisories, io) {
   printContractHealthSection(advisories.contractHealth, io);
   printAmbientStateSection(advisories.ambientState, io);
+  printPhysicalCohesionSection(
+    advisories.physicalCohesion,
+    advisories.physicalCohesion?.reshapePilot,
+    io
+  );
 }

package/bin/lib/doctor-plan.mjs

@@ -55,7 +55,6 @@ function normalize(value) {
 }
 
 
-
 export function computeCoverage(root, config, files, rules) {
   const layers = config.layers ?? [];
   const counts = new Map(layers.map((layer) => [layer.name, 0]));
@@ -425,7 +424,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     patternBets: patternBetsForLoop,
     designSmells,
   });
-  const { contractHealth, ambientState } = computeDoctorAdvisories(root, config, cov, rules, files, options.ts); // W01+U05 advisories — never a verdict
+  const { contractHealth, ambientState, physicalCohesion } = computeDoctorAdvisories(root, config, cov, rules, files, options.ts); // W01+U05+X04 advisories — never a verdict
 
   if (asJson) {
     console.log(
@@ -462,10 +461,11 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             goldenPattern,
             // Q04: one-pilot loop (extraction card → re-doctor).
             pilotLoop,
-            // W01: contract-health meta-lint (advisory; verdict unchanged).
+            // Advisories, never a verdict: W01 contract health, U05 ambient
+            // state (opt-in), X04 physical cohesion + proposed reshape pilot.
             contractHealth,
-            // U05: ambient-state sensor (advisory; opt-in; verdict unchanged).
             ambientState,
+            physicalCohesion,
             governed: cov.governed,
             emptyLayers: cov.emptyLayers,
             layersWithoutRules: cov.layersWithoutRules,
@@ -647,7 +647,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     );
   }
 
-  printDoctorAdvisories({ contractHealth, ambientState }, { line, warn, color }); // advisory sections
+  printDoctorAdvisories({ contractHealth, ambientState, physicalCohesion }, { line, warn, color }); // advisory sections
 
   console.log('');
   console.log(color.bold('Coverage'));