arkgate 3.5.0 → 3.6.1

package/CHANGELOG.md

@@ -4,9 +4,68 @@ All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are do
 
 ## Unreleased
 
+## 3.6.1 — 2026-07-17
+
+Codex project-scoped MCP fix. **No breaking** CLI, MCP tool, or `ark.config.json` changes.
+**No gate weaken.**
+
+### Fixed
+
+- **Codex MCP follows the active repository:** `--install-agent-gates --tools codex` now writes
+  `.codex/config.toml` with relative project paths. Each repository owns its primary `ark`
+  binding, so `ark upgrade` no longer leaves Codex resolving `ark://manifest` through another
+  permanent project registered in the global home config.
+- **Doctor effective-config honesty:** Codex advisory-MCP capability and adoption checks prefer
+  a valid project `.codex/config.toml`; an unrelated `$CODEX_HOME` primary no longer produces a
+  false `write-path-none` or `codex-home-multi-project` warning.
+- **Ephemeral worktree cleanup:** roots under `.claude/worktrees`, `.codex/worktrees`, or
+  `.grok/worktrees` are treated as temporary instead of permanent global MCP owners.
+
+### Changed
+
+- `$CODEX_HOME/config.toml` remains an explicit compatibility fallback via `--codex-home`.
+  Normal `--tools codex` installs no longer mutate the global MCP registry, and skills-only
+  home refreshes cannot accidentally rebind its primary server.
+
+## 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 the amarilla adoption session): the HTML report reaches
+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`,

package/README.md

@@ -16,10 +16,9 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 3.4.0** is current stable: opt-in capability walls (`pure: true` or
-> `capabilities.deny` per layer, enforced on every adapter), the advisory ambient-state sensor,
-> and the measured pre-tool path — completing 3.3's evidence slice.
-> [Release notes](docs/releases/3.4.0.md).
+> **ArkGate 3.6.1** is current stable: Codex MCP configuration is project-scoped, doctor
+> recognizes the effective project binding, and stale agent worktrees no longer become
+> permanent global MCP owners. [Release notes](docs/releases/3.6.1.md).
 
 ---
 
@@ -383,7 +382,7 @@ for real systems. Details: [production-hardening.md](https://github.com/pedrokni
 | 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) |
+| Latest release (3.6.1) | [release notes](docs/releases/3.6.1.md) · [3.0.0 baseline](docs/releases/3.0.0.md) |
 | Roadmap and decisions | [ROADMAP.md](ROADMAP.md) · [ADRs](docs/adr/) · [Changelog](CHANGELOG.md) |
 
 ---

package/bin/ark.mjs

@@ -227,8 +227,8 @@ async function upgrade(args) {
   if (status !== 0) return status;
 
   // Codex home skill catalog is $CODEX_HOME/skills/<name>/SKILL.md (repo uses .agents/skills/).
-  // Refresh home when a Codex home exists. --force rewrites temp/upgrade MCP roots to this
-  // project + arkgate-mcp. Non-fatal: a permission error (e.g. sandbox) shouldn't fail upgrade.
+  // Refresh home skills when a Codex home exists. Project MCP is installed above in
+  // .codex/config.toml. Non-fatal: a permission error (e.g. sandbox) shouldn't fail upgrade.
   const codexHomeBase = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
   if (fs.existsSync(codexHomeBase)) {
     console.log(`\n     Refreshing Codex home (${codexHomeBase})…`);

package/bin/lib/agent-gates.mjs

@@ -8,6 +8,7 @@ export {
   codexArkBlockNeedsRewrite,
   codexConfigPath,
   codexPrimaryTable,
+  codexProjectMcpIsValid,
   codexProjectSlug,
   codexPromptsDir,
   codexSkillsDir,
@@ -23,6 +24,7 @@ export {
 export {
   PREFERRED_MCP_BIN,
   claudeSettings,
+  codexProjectConfig,
   grokHooks,
   grokProjectConfig,
 } from './hook-templates.mjs';

package/bin/lib/ci-and-commands.mjs

@@ -238,10 +238,8 @@ export function mcpJson(root) {
   }, null, 2)}\n`;
 }
 
-// Sample for docs/ — `ark-check --install-agent-gates --tools codex` auto-merges the real
-// block (with absolute paths) into ~/.codex/config.toml. This copy is a reference only, so
-// it flags the two gotchas of hand-editing the global config: absolute paths (config.toml is
-// loaded without the project as cwd) and the required restart.
+// Optional home fallback reference. Normal Codex installs write the project-scoped
+// `.codex/config.toml`; `--codex-home` is for older clients or an explicit global binding.
 export function codexTomlSnippet(root) {
   const { command, args } = execCommandParts(root, PREFERRED_MCP_BIN, [
     '--root',
@@ -250,10 +248,9 @@ export function codexTomlSnippet(root) {
     '/absolute/path/to/project/ark.config.json',
   ]);
   const argsToml = args.map((value) => `"${value}"`).join(', ');
-  return `# Add to ~/.codex/config.toml (or $CODEX_HOME/config.toml), then RESTART Codex —
-# it does not hot-load MCP servers. Use ABSOLUTE paths: config.toml is global, so
-# "." would resolve against Codex's launch dir, not this project. Prefer:
-#   ark-check --install-agent-gates --tools codex   (auto-merges the absolute paths)
+  return `# Optional global fallback for older Codex clients. Modern Codex uses the generated
+# project-scoped .codex/config.toml instead. If you install this fallback manually, restart
+# Codex and keep ABSOLUTE paths because $CODEX_HOME/config.toml is global.
 [mcp_servers.ark]
 command = "${command}"
 args = [${argsToml}]

package/bin/lib/codex-home.mjs

@@ -47,6 +47,7 @@ export function isTempOrUpgradeRoot(p) {
     /\/tmp\//i.test(n) ||
     /\/Temp\//i.test(n) ||
     /ark-upgrade/i.test(n) ||
+    /\/(?:\.claude|\.codex|\.grok)\/worktrees\//i.test(n) ||
     /\/T\/(?:ark-|grok-)/i.test(n) ||
     /[\\/]AppData[\\/]Local[\\/]Temp[\\/]/i.test(n)
   );
@@ -144,6 +145,23 @@ export function codexScopedTableForRoot(tomlText, absRoot) {
   return null;
 }
 
+/** True when project TOML owns the primary Ark MCP binding for that project. */
+export function codexProjectMcpIsValid(tomlText, projectRoot) {
+  const resolvedRoot = path.resolve(projectRoot);
+  const primary = codexPrimaryTable(tomlText);
+  if (!primary?.root || !/\b(ark|arkgate)-mcp\b/.test(primary.block)) return false;
+  const config = primary.block.match(/"--config"\s*,\s*"([^"]+)"/)?.[1];
+  if (!config) return false;
+  try {
+    return (
+      path.resolve(resolvedRoot, primary.root) === resolvedRoot &&
+      path.resolve(resolvedRoot, config) === path.join(resolvedRoot, 'ark.config.json')
+    );
+  } catch {
+    return false;
+  }
+}
+
 /** Extract --root from primary [mcp_servers.ark]. */
 export function extractCodexArkRootFromToml(tomlText) {
   return codexPrimaryTable(tomlText)?.root ?? null;
@@ -236,14 +254,11 @@ export function assessCodexHomeMcp(tomlText, absRoot) {
       message: scopedTable
         ? `Codex primary [mcp_servers.ark] is bound to another project (${rootArg}); ` +
           `this project is registered as [mcp_servers.${scopedTable}]. ` +
-          `Codex may still prefer the primary binding for ark://manifest — rebind if this repo should own it.`
+          `Install the project-scoped binding so this repo owns ark://manifest when active.`
         : `Codex home primary MCP --root is another permanent project ` +
           `(${rootArg || 'missing'} ≠ ${resolvedRoot}). ` +
-          `Install without --force adds a scoped [mcp_servers.ark_<slug>] table and leaves primary unchanged; ` +
-          `--force rebinds primary to this project.`,
-      fixArgs: scopedTable
-        ? '--install-agent-gates --tools codex --force'
-        : '--install-agent-gates --tools codex',
+          `Install the project-scoped binding for this repo; the global primary can remain unchanged.`,
+      fixArgs: '--install-agent-gates --tools codex',
     };
   }
 

package/bin/lib/contract-smells.mjs

@@ -63,19 +63,26 @@ function nameTokens(name) {
 }
 
 /**
- * X03 — an adapter reaching its OWN family's infrastructure base is not a
- * lateral peer: same leading family token and EVERY remaining target token
- * reads as an infra base (Infra/Base/Core/Shared/…) — `PaymentsCoreAdapters`
- * is still a sibling, not a base. Field origin: amarilla, where
- * `<Family>Adapters -> <Family>Infra` fired as adapter-to-adapter.
+ * 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];
-  if (family.length < 2 || family.toLowerCase() !== fromTokens[0].toLowerCase()) 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));
 }
 
@@ -290,9 +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: [] };
+  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;
@@ -545,9 +571,9 @@ export function formatContractHealthLines(smells, health) {
   const gw = health?.governanceWeight;
   const weightNoteworthy = gw?.weight === 'heavy' || gw?.weight === 'light';
   const lc = health?.ackLifecycle;
-  // Undated acks must surface even when every smell is suppressed — that is
-  // exactly the fossilization case X02 exists to catch.
-  const lifecycleNoteworthy = (lc?.undated ?? 0) > 0;
+  // 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;
   }
@@ -591,6 +617,14 @@ export function formatContractHealthLines(smells, health) {
       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',
@@ -610,20 +644,23 @@ export function formatContractHealthLines(smells, health) {
  * `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}> }} [ackLifecycle]
+ * @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,
-  ackLifecycle = { undated: 0, malformed: 0, expired: [] }
+  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,
@@ -634,6 +671,8 @@ export function summarizeContractHealth(
       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:

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'));

package/bin/lib/gate-files.mjs

@@ -125,7 +125,7 @@ const COMPACT_HOST_FILES = {
   claude: ['.claude/settings.json'],
   grok: ['.grok/config.toml', '.grok/hooks/ark-write-gate.json'],
   cursor: ['.cursor/mcp.json'],
-  codex: ['.codex/hooks.json'],
+  codex: ['.codex/hooks.json', '.codex/config.toml'],
   windsurf: ['.windsurf/rules/ark.md'],
   cline: ['.clinerules/ark.md'],
   copilot: ['.github/copilot-instructions.md'],

package/bin/lib/hook-templates.mjs

@@ -73,8 +73,28 @@ export function codexHooks(root) {
   }, null, 2)}\n`;
 }
 
+// Codex project config: modern Codex resolves .codex/config.toml from the active
+// project, so the primary `ark` binding can stay local instead of competing in
+// the user's global $CODEX_HOME across every adopted repository.
+export function codexProjectConfig(root) {
+  const { command, args } = execCommandParts(root, PREFERRED_MCP_BIN, [
+    '--root',
+    '.',
+    '--config',
+    'ark.config.json',
+  ]);
+  const esc = (value) => value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  const argsToml = args.map((value) => `"${esc(value)}"`).join(', ');
+  return `# Generated by ark-check --install-agent-gates (Codex project scope).
+# Restart Codex after changes; MCP servers are loaded when the project session starts.
+[mcp_servers.ark]
+command = "${esc(command)}"
+args = [${argsToml}]
+`;
+}
+
 // Grok Build project config: MCP registration (commit-friendly relative paths — unlike
-// Codex's global config.toml, Grok loads .grok/config.toml from the project).
+// the optional Codex home fallback, Grok loads .grok/config.toml from the project).
 export function grokProjectConfig(root) {
   const { command, args } = execCommandParts(root, PREFERRED_MCP_BIN, [
     '--root',

package/bin/lib/html-report-advisories.mjs

@@ -52,11 +52,13 @@ function ackLifecycleHtml(lc) {
   if (!lc) return '';
   const rows = [];
   if ((lc.expiredCount ?? 0) > 0) {
-    const edges = (lc.expired ?? [])
+    const list = lc.expired ?? [];
+    const edges = list
       .map((e) => `<code>${esc(e.edge)}</code> (review-by ${esc(e.reviewBy)})`)
       .join(' · ');
+    const more = lc.expiredCount > list.length ? ` …(+${lc.expiredCount - list.length} more)` : '';
     rows.push(
-      `<p><span class="tag warn">expired</span> ${lc.expiredCount} acknowledgment(s) past review-by — no longer applied, the smell is active again: ${edges}</p>`
+      `<p><span class="tag warn">expired</span> ${lc.expiredCount} acknowledgment(s) past review-by — no longer applied, the smell is active again: ${edges}${more}</p>`
     );
   }
   if ((lc.malformed ?? 0) > 0) {
@@ -69,6 +71,15 @@ function ackLifecycleHtml(lc) {
       `<p class="muted">${lc.undated} applied acknowledgment(s) have no review-by date — add one so migration acks cannot fossilize.</p>`
     );
   }
+  if ((lc.staleCount ?? 0) > 0) {
+    // Plain "+N more": doctor JSON caps its own list, so pointing there for
+    // the remainder would over-promise (cross-model review finding).
+    const edges = (lc.stale ?? []).slice(0, 4).map((s) => `<code>${esc(s.edge)}</code>`).join(' · ');
+    const more = lc.staleCount > 4 ? ` …(+${lc.staleCount - 4} more)` : '';
+    rows.push(
+      `<p class="muted">${lc.staleCount} acknowledgment(s) match no detected edge — stale; fix the edge string or delete the entry: ${edges}${more}</p>`
+    );
+  }
   return rows.join('\n');
 }
 
@@ -85,15 +96,21 @@ function contractHealthHtml(health) {
   const body = smells.length === 0
     ? `<p class="muted">No contract smells detected — no explicitly bidirectional allows, peripheral-into-core allows, lateral adapter allows, or dead rules beyond what is acknowledged.</p>`
     : smells
-        .map(
-          (s) => `
+        .map((s) => {
+          const evidence = Array.isArray(s.evidence) ? s.evidence : [];
+          // X07 — the cap must announce itself: a 12-edge smell showing 6
+          // codes with no marker reads as the whole story.
+          const more = evidence.length > 6
+            ? ` <span class="muted">…(+${evidence.length - 6} more in doctor JSON)</span>`
+            : '';
+          return `
       <div class="finding">
         <p><span class="tag warn">${esc(s.id)}</span> ${esc(s.outcome ?? s.message ?? '')}</p>
         <p class="muted">${esc(s.message ?? '')}</p>
-        <p class="muted">evidence: <code>${(s.evidence ?? []).slice(0, 6).map(esc).join('</code> · <code>')}</code></p>
+        <p class="muted">evidence: <code>${evidence.slice(0, 6).map(esc).join('</code> · <code>')}</code>${more}</p>
         <p class="muted">fix: ${esc(s.fix ?? '')}</p>
-      </div>`
-        )
+      </div>`;
+        })
         .join('\n');
   return `
   <section data-advisory="contractHealth">
@@ -135,6 +152,31 @@ function ambientStateHtml(state) {
   </section>`;
 }
 
+function physicalCohesionHtml(pc) {
+  if (!pc) return '';
+  const findings = Array.isArray(pc.findings) ? pc.findings : [];
+  const body = findings.length === 0
+    ? '<p class="muted">No mirrored concept explosion detected — no concept clusters over the calibrated thresholds (ADR 0010).</p>'
+    : findings
+        .map((f) => {
+          const anchors = (f.anchors ?? [])
+            .map((a) => `<code>${esc(a.path)}</code> (${a.files}${a.fixedByConvention ? ', fixed by convention' : ''})`)
+            .join(' · ');
+          return `<p><span class="tag warn">${esc(f.concept)}</span> ${f.files} file(s) across ${f.anchorCount} anchor(s)${f.mirrored ? ' — mirrored' : ''}: ${anchors}</p>`;
+        })
+        .join('\n') +
+      (pc.truncated > 0 ? `<p class="muted">…(+${pc.truncated} more concept(s) in doctor JSON)</p>` : '');
+  const pilot = pc.reshapePilot?.nextPilot
+    ? `<p class="muted">next pilot (proposed, never applied): ${esc(pc.reshapePilot.nextPilot.pilotTarget)} — one pilot at a time via /ark-loop; merges are judgment cards only.</p>`
+    : '';
+  return `
+  <section data-advisory="physicalCohesion">
+    <h2>Physical cohesion <span class="muted">(advisory — facts, not a score; the verdict is unchanged)</span></h2>
+    ${body}
+    ${pilot}
+  </section>`;
+}
+
 /**
  * Render every doctor advisory as report sections. Keys must cover everything
  * `computeDoctorAdvisories` returns — the parity guard enforces it.
@@ -143,7 +185,11 @@ function ambientStateHtml(state) {
 export function renderAdvisorySections(advisories, escape) {
   if (!advisories || typeof advisories !== 'object') return '';
   if (typeof escape === 'function') esc = escape;
-  return [contractHealthHtml(advisories.contractHealth), ambientStateHtml(advisories.ambientState)]
+  return [
+    contractHealthHtml(advisories.contractHealth),
+    ambientStateHtml(advisories.ambientState),
+    physicalCohesionHtml(advisories.physicalCohesion),
+  ]
     .filter(Boolean)
     .join('\n');
 }

package/bin/lib/install-migrate.mjs

@@ -15,6 +15,7 @@ import {
   codexSkillsDir,
   codexConfigPath,
   isTempOrUpgradeRoot,
+  upsertCodexMcpTable,
   usesDefaultCodexHome,
   wireCodexMcp,
 } from './codex-home.mjs';
@@ -22,6 +23,7 @@ import {
   PREFERRED_MCP_BIN,
   claudeSettings,
   codexHooks,
+  codexProjectConfig,
   grokHooks,
   grokProjectConfig,
 } from './hook-templates.mjs';
@@ -279,6 +281,7 @@ export function runInstallAgentGates(args) {
     }
     if (tools.has('codex')) {
       templates.push(['.codex/hooks.json', codexHooks(root)]);
+      templates.push(['.codex/config.toml', codexProjectConfig(root)]);
       if (!args.compact) templates.push(['docs/ark-codex-config.toml', codexTomlSnippet(root)]);
     }
     if (tools.has('grok')) {
@@ -341,14 +344,29 @@ export function runInstallAgentGates(args) {
     }
   }
 
-  const results = templates.map(([relativePath, content]) =>
-    writeTemplate(
+  const results = templates.map(([relativePath, content]) => {
+    if (relativePath === '.codex/config.toml') {
+      const fullPath = path.join(root, relativePath);
+      let existing = '';
+      try {
+        existing = fs.readFileSync(fullPath, 'utf8');
+      } catch {
+        // A missing project config starts from the generated Ark table.
+      }
+      const tableStart = content.indexOf('[mcp_servers.ark]');
+      const generatedPrelude = tableStart > 0 ? content.slice(0, tableStart) : '';
+      const mergeBase = generatedPrelude ? existing.replace(generatedPrelude, '') : existing;
+      const merged = upsertCodexMcpTable(mergeBase, 'ark', content);
+      if (merged === existing) return { relativePath, status: 'skipped' };
+      return writeTemplate(root, relativePath, merged, true);
+    }
+    return writeTemplate(
       root,
       relativePath,
       content,
       args.force || (args.compact && relativePath === 'AGENTS.md' && priorCompactHost !== null)
-    )
-  );
+    );
+  });
 
   console.log('Ark agent gate templates:');
   let staleSkipped = 0;
@@ -427,11 +445,8 @@ export function runInstallAgentGates(args) {
     }
   }
 
-  // Auto-wire the ark MCP server into Codex's home config.toml. Claude and Cursor get
-  // machine-readable registrations (.claude/settings.json, .cursor/mcp.json) written as repo
-  // templates above; Codex reads MCP servers only from ~/.codex/config.toml, so it needs a
-  // home-dir merge instead. Fires whenever Codex is in play so `ark://manifest` is live
-  // without a manual copy step.
+  // Optional legacy/home fallback. Normal Codex installs use the project-scoped
+  // .codex/config.toml above, avoiding cross-project primary binding conflicts.
   //
   // Skip home MCP mutation when the project root is a temp/upgrade scratch *and*
   // CODEX_HOME is the default (~/.codex). Fixtures and agent smokes must not rewrite
@@ -439,7 +454,7 @@ export function runInstallAgentGates(args) {
   // home *skills* below; MCP binding of a temp root into default home is never safe.
   // A redirected CODEX_HOME (tests/isolation) may still wire as requested.
   let codexMcp = null;
-  const wantCodexWire = !args.compact && (tools.has('codex') || args.codexHome);
+  const wantCodexWire = !args.compact && !args.skillsOnly && args.codexHome;
   const skipHomeWire =
     wantCodexWire && isTempOrUpgradeRoot(root) && usesDefaultCodexHome();
   if (wantCodexWire && !skipHomeWire) {
@@ -475,7 +490,7 @@ export function runInstallAgentGates(args) {
   }
   if (codexMcp?.status === 'failed') {
     console.error(
-      `\nWarning: Codex home MCP registration failed (${codexMcp.message}). Repo gates were written; fix ~/.codex access or re-run with --tools codex --force.`
+      `\nWarning: Codex home MCP registration failed (${codexMcp.message}). Repo gates were written; fix ~/.codex access or re-run with --codex-home --force.`
     );
   }
   if (writeRequest.host) {