arkgate 3.0.3 → 3.0.5

package/CHANGELOG.md

@@ -4,7 +4,75 @@ All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are do
 
 ## Unreleased
 
-No changes are scheduled after 3.0.3.
+No changes are scheduled after 3.0.5.
+
+## 3.0.5 — 2026-07-14
+
+Codex host skill catalog + residual honesty. **No breaking** CLI or `ark.config.json`
+changes. **No gate weaken.**
+
+### Fixed
+
+- **Codex `/ark-*` skills not invocable:** install wrote flat `.codex/prompts/*.md`, which
+  Codex does not load as skills. Repo catalog is now `.agents/skills/<name>/SKILL.md`
+  (Agent Skills REPO scope); optional home catalog is `$CODEX_HOME/skills/<name>/SKILL.md`
+  via `--codex-home`. Post-install verifies AGENTS.md `/ark-*` refs against each selected
+  host catalog.
+- **Temp-root MCP footgun:** `--codex-home` no longer rebinds primary `[mcp_servers.ark]` in
+  the default `~/.codex/config.toml` when the project root is a temp/upgrade path (skills may
+  still refresh under an isolated or real home).
+- **Multi-host skill hints:** Codex legacy-prompts-only debt no longer suppresses missing/stale
+  skill reports for Claude/Cursor/other hosts in doctor and `ark-check` human output.
+- **Deferred Codex home debt severity:** outside a Codex session, home skill gaps are dim/info
+  (not warn) and are not Top actions; when the session host is Codex they stay warn + fix.
+
+### Added
+
+- **Skill parity sensors:** missing / stale / legacy-prompts-only for repo and home catalogs,
+  with package `arkVersion` stamps; doctor and JSON expose concrete refresh fixes
+  (`--skills-only --tools codex` and/or `--codex-home`).
+- **CI fail-closed detection:** workflows with ark-check but only `--strict-config` (or no
+  strict flags) surface `enforcement-ci-not-fail-closed` (warn) with a `--strict-merge` fix.
+  `--strict` / `--strict-merge` / `--require-gates` count as fail-closed. Merge-gate inventory
+  evidence requires that fail-closed profile.
+- **Codex write-path honesty:** install and doctor state local Codex write is advisory (MCP +
+  best-effort hooks; not Claude/Grok hard-write + repair); CI `--strict-merge` + required
+  status is the hard merge backstop.
+
+Release note: `docs/releases/3.0.5.md`.
+
+## 3.0.4 — 2026-07-14
+
+Report honesty + showcase depth patch. **No breaking** CLI or `ark.config.json` changes.
+**No gate weaken.**
+
+### Fixed
+
+- **HTML report false ADAPT:** `computeReportFitness` counted *any* `optional: true` layer
+  with files as `coreOptionalWithFiles`, so doctor could report **ENFORCE** while
+  `ark-report.html` / `latest.json` mode stayed **ADAPT** (secondary layers like
+  SharedKernel / Integration / Workflow). Report now uses the same `CORE_LAYER_NAMES`
+  filter as doctor adoption (`DomainModel`, `ApplicationOrchestration`,
+  `PresentationAdapters`, `PersistenceAdapters`).
+- **False adoption gap `write-path-none` on report/CI:** when `activeHost` is `unknown`
+  (plain `npx ark-check --report` outside an agent session) but the repo inventory already
+  has hard-write hooks or advisory MCP for Claude/Grok/Cursor/Codex, doctor/report no longer
+  open a `write-path-none` adoption gap. Session projection still reports `mode: none` for
+  honesty (other hosts' hooks are not a guarantee for this process). `detectActiveAgentHost`
+  also recognizes `GROK_AGENT`.
+
+### Added
+
+- **Report metric hints:** HTML showcase KPIs (hero, adoption, contract density, debt) show
+  plain-language micro-copy under each tile plus native tooltips; PASS/mode badges and score
+  parts (Coverage/Clean/Gates/Rules) explain what they mean for newcomers.
+- **Report design-depth strip:** `ark-check --report` includes doctor-parity Shape residual
+  (design-weak badge, smell outcomes, one next pilot, post-green door, optional golden pattern).
+  Clean ENFORCE with no smells shows a short “Design depth · OK” note (only when sensors ran).
+- **Report adoption extras:** write-path line (active host · mode · inventory on disk) and a
+  fixed baseline-policy legend (`keep-empty` / `active-ratchet` / `absent`).
+
+Release note: `docs/releases/3.0.4.md`.
 
 ## 3.0.3 — 2026-07-13
 

package/bin/ark-check.mjs

@@ -33,7 +33,9 @@ import {
   loadTypeScript,
   detectSkillGaps,
   detectCodexHomeGap,
-  detectActiveAgentHost,
+  detectCodexRepoSkillGap,
+  codexConcernIsActive,
+  printSkillAndCodexGapHints,
   missingGates,
   staleRunnerGateFiles,
   brokenMcpGateFiles,
@@ -44,7 +46,6 @@ import {
   arkPackageVersion,
   compactRouterHost,
   REQUIRED_GATE_FILES,
-  codexPromptsDir,
   detectWritePathCapabilities,
 } from './lib/agent-gates.mjs';
 import { syncBaselineIntoCheckSurfaces } from './lib/field-install.mjs';
@@ -58,6 +59,7 @@ import {
   reportsDir,
   readJsonSafe,
 } from './lib/html-report.mjs';
+import { buildReportDepthPayload } from './lib/html-report-depth.mjs';
 import { shouldOpenHtmlReport, openHtmlInBrowser } from './lib/open-html.mjs';
 import {
   computeCoverage,
@@ -300,8 +302,8 @@ function usage() {
     '(instruction-tier rule files derived from the same contract).',
     'It also installs the /ark-* skills shipped in templates/skills/ into each',
     'detected tool\'s command location (.claude/skills/, .cursor/commands/,',
-    '.codex/prompts/, .grok/skills/, .windsurf/workflows/, .clinerules/workflows/,',
-    '.github/prompts/).',
+    '.agents/skills/ (Codex REPO catalog), .grok/skills/, .windsurf/workflows/,',
+    '.clinerules/workflows/, .github/prompts/).',
     'Kiro, Roo, Continue, and Gemini have no command mechanism and receive only their',
     'rule file. Existing files are never overwritten without --force, so re-running',
     'after an update only adds what is missing. --skills-only restricts the write to',
@@ -1228,6 +1230,8 @@ async function main() {
 
   const skillGaps = detectSkillGaps(root);
   const codexHomeGap = detectCodexHomeGap(root);
+  const codexRepoSkillGap = detectCodexRepoSkillGap(root);
+  const codexSessionActive = codexConcernIsActive();
 
   if (args.report) {
     const exampleByLayer = new Map();
@@ -1266,6 +1270,13 @@ async function main() {
     const existingOrigin = args.resetOrigin
       ? null
       : readJsonSafe(path.join(reportsDir(root), 'origin.json'));
+    const { adoption: adoptionForReport, designDepth } = buildReportDepthPayload(
+      root,
+      config,
+      files,
+      coverage,
+      activeViolations
+    );
     const reportPayload = {
       root,
       config,
@@ -1282,6 +1293,8 @@ async function main() {
       originSnapshot: existingOrigin,
       currentSnapshot,
       originJustCreated: !existingOrigin,
+      adoption: adoptionForReport,
+      designDepth,
     };
     const html = args.beginner
       ? renderBeginnerHtmlReport(reportPayload)
@@ -1362,7 +1375,15 @@ async function main() {
       warnings,
       ...(activeViolations.length > 0 ? { summary: summarizeViolations(activeViolations) } : {}),
       ...(skillGaps.length > 0 ? { skillGaps } : {}),
-      ...(codexHomeGap ? { codexHomeGap } : {}),
+      ...(codexHomeGap
+        ? {
+            codexHomeGap: {
+              ...codexHomeGap,
+              deferred: !codexSessionActive,
+            },
+          }
+        : {}),
+      ...(codexRepoSkillGap ? { codexRepoSkillGap } : {}),
     }, null, 2));
   } else {
     for (const warning of warnings) {
@@ -1410,30 +1431,13 @@ async function main() {
       printViolationBreakdown(summarizeViolations(activeViolations), { toStderr: true });
     }
 
-    if (skillGaps.length > 0) {
-      const missingTotal = skillGaps.reduce((sum, gap) => sum + gap.missing, 0);
-      const staleTotal = skillGaps.reduce((sum, gap) => sum + gap.stale, 0);
-      const tools = skillGaps.map((gap) => gap.tool).join(', ');
-      if (missingTotal > 0) {
-        console.log(
-          color.dim(
-            `${missingTotal} /ark-* skill(s) not installed for ${tools} (this Ark version ships them). ` +
-              `Install: ${arkCommand(root, 'ark-check', '--install-agent-gates')}`
-          )
-        );
-      }
-      if (staleTotal > 0) {
-        // Stale skills already exist, so refreshing needs --force. --skills-only
-        // scopes the overwrite to the canonical skills, leaving a customized
-        // AGENTS.md / settings / CI untouched (a bare --force would clobber them).
-        console.log(
-          color.dim(
-            `${staleTotal} /ark-* skill(s) outdated for ${tools} (this Ark ships newer versions). ` +
-              `Refresh: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --force')}`
-          )
-        );
-      }
-    }
+    printSkillAndCodexGapHints(root, {
+      skillGaps,
+      codexHomeGap,
+      codexRepoSkillGap,
+      codexSessionActive,
+      color,
+    });
 
     const staleRunners = staleRunnerGateFiles(root);
     if (staleRunners.length > 0) {
@@ -1454,27 +1458,6 @@ async function main() {
         )
       );
     }
-
-    if (codexHomeGap) {
-      const parts = [];
-      if (codexHomeGap.missing > 0) parts.push(`${codexHomeGap.missing} missing`);
-      if (codexHomeGap.stale > 0) parts.push(`${codexHomeGap.stale} outdated`);
-      // Advisory always; when session host is known and not Codex, say so so
-      // /ark-upgrade does not chase home prompts as Incomplete.
-      const activeHost = detectActiveAgentHost();
-      const deferredNote =
-        activeHost != null && activeHost !== 'codex'
-          ? ' Deferred unless you use Codex — not a blocker for Grok/Claude/Cursor. '
-          : ' ';
-      console.log(
-        color.dim(
-          `/ark-* skills in ${codexPromptsDir()} are behind this Ark (${parts.join(', ')}).` +
-            deferredNote +
-            `Codex loads them from $CODEX_HOME/prompts, not the repo. ` +
-            `When using Codex: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --codex-home --force')}`
-        )
-      );
-    }
   }
 
   if (args.watch) {

package/bin/ark.mjs

@@ -213,9 +213,9 @@ async function upgrade(args) {
   let status = runArkCheck(['--root', root, '--install-agent-gates'], { cwd: root });
   if (status !== 0) return status;
 
-  // Codex loads slash-command prompts from $CODEX_HOME/prompts, not the repo — refresh those
-  // 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 the whole upgrade.
+  // 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.
   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

@@ -10,6 +10,7 @@ export {
   codexPrimaryTable,
   codexProjectSlug,
   codexPromptsDir,
+  codexSkillsDir,
   codexScopedTableForRoot,
   extractCodexArkRootFromToml,
   extractCodexRootFromBlock,
@@ -77,6 +78,7 @@ export {
   normalizeToolsList,
   resolveTools,
   KNOWN_TOOLS,
+  SKILL_TOOL_TARGETS,
   detectActiveAgentHost,
   codexConcernIsActive,
   arkPackageVersion,
@@ -86,7 +88,13 @@ export {
   skillTemplates,
   skillTemplateNames,
   detectCodexHomeGap,
+  detectCodexRepoSkillGap,
+  assessCodexSkillParity,
+  assessSkillCatalogParity,
   detectSkillGaps,
+  agentsMdSkillRefs,
+  verifyHostSkillCatalog,
+  printSkillAndCodexGapHints,
 } from './skill-install.mjs';
 
 export { detectDeployPathQuality } from './deploy-path.mjs';
@@ -101,6 +109,7 @@ export {
 export {
   detectPreCommitArk,
   detectCiEnforcement,
+  classifyArkCheckFlags,
   detectConfigGateDrift,
   jobIdsThatRunArkCheck,
   isArkRequiredStatusCheck,

package/bin/lib/codex-home.mjs

@@ -10,12 +10,21 @@ import { execCommandParts } from '../ark-shared.mjs';
 
 export const PREFERRED_CODEX_MCP_BIN = 'arkgate-mcp';
 
-/** Where Codex loads slash-command prompts ($CODEX_HOME/prompts). */
+/** Where Codex loads slash-command prompts ($CODEX_HOME/prompts) — legacy, not the skill catalog. */
 export function codexPromptsDir() {
   const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
   return path.join(base, 'prompts');
 }
 
+/**
+ * Where Codex loads user/home SKILL.md skills ($CODEX_HOME/skills/<name>/SKILL.md).
+ * Repo-scoped skills live at `.agents/skills/<name>/SKILL.md` (Agent Skills standard).
+ */
+export function codexSkillsDir() {
+  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(base, 'skills');
+}
+
 /** Where Codex loads MCP servers ($CODEX_HOME/config.toml) — global, not project-local. */
 export function codexConfigPath() {
   const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');

package/bin/lib/doctor-plan.mjs

@@ -14,6 +14,8 @@ import {
 import {
   collectAdoptionGaps,
   detectSkillGaps,
+  detectCodexHomeGap,
+  codexConcernIsActive,
   detectWritePathCapabilities,
   missingGates,
   staleRunnerGateFiles,
@@ -405,8 +407,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     ? [...baseline.keys].filter((key) => !currentKeys.has(key)).length
     : 0;
   const activeCount = violations.length - suppressed;
-  const missingSkills = skillGaps.reduce((sum, gap) => sum + gap.missing, 0);
-  const staleSkills = skillGaps.reduce((sum, gap) => sum + gap.stale, 0);
   const designSmells = detectDesignSmells(root, config, files, cov);
   const designFitness = summarizeDesignFitness(designSmells, {
     activeViolations: activeCount,
@@ -769,11 +769,36 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     line(bad, `Missing gates: ${gatesMissing.join(', ')}`);
     actions.push(`install gates (${arkCommand(root, 'ark-check', '--install-agent-gates')})`);
   }
-  if (missingSkills + staleSkills === 0) line(ok, '/ark-* skills current for detected tools');
-  else {
-    line(warn, `${missingSkills} missing / ${staleSkills} outdated /ark-* skill(s) for ${skillGaps.map((g) => g.tool).join(', ')}`);
+  // Report Codex legacy prompts and other-host missing/stale independently (never exclusive).
+  const legacyCodex = skillGaps.some((g) => g.tool === 'codex' && g.legacyPromptsOnly);
+  const remainingGaps = skillGaps.filter((g) => !(g.tool === 'codex' && g.legacyPromptsOnly));
+  const remMiss = remainingGaps.reduce((s, g) => s + g.missing, 0);
+  const remStale = remainingGaps.reduce((s, g) => s + g.stale, 0);
+  if (remMiss + remStale === 0 && !legacyCodex) line(ok, '/ark-* skills current for detected tools');
+  if (legacyCodex) {
+    line(warn, 'Codex: legacy flat .codex/prompts only (not a loadable skill catalog)');
+    actions.push('install Codex SKILL.md catalog (--install-agent-gates --skills-only --tools codex --force)');
+  }
+  if (remMiss + remStale > 0) {
+    line(warn, `${remMiss} missing / ${remStale} outdated /ark-* skill(s) for ${remainingGaps.map((g) => g.tool).join(', ')}`);
     actions.push('refresh /ark-* skills (--install-agent-gates --skills-only --force)');
   }
+  const codexHomeGap = detectCodexHomeGap(root);
+  if (codexHomeGap) {
+    const parts = [
+      codexHomeGap.legacyPromptsOnly ? 'legacy-prompts-only' : null,
+      codexHomeGap.missing > 0 ? `${codexHomeGap.missing} missing` : null,
+      codexHomeGap.stale > 0 ? `${codexHomeGap.stale} outdated` : null,
+    ].filter(Boolean);
+    const deferred = !codexConcernIsActive();
+    // Deferred home debt is dim/info (not warn) so non-Codex sessions are not "incomplete".
+    if (deferred) {
+      line(color.dim('·'), color.dim(`Codex home skills ${parts.join(', ')} (deferred — not on Codex session)`));
+    } else {
+      line(warn, `Codex home skills ${parts.join(', ')}`);
+      actions.push('refresh Codex home skills (--install-agent-gates --skills-only --codex-home --force)');
+    }
+  }
 
   console.log('');
   console.log(color.bold('Baseline'));

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

@@ -0,0 +1,282 @@
+/**
+ * Design-depth + adoption extras for the HTML showcase report.
+ * Kept separate from html-report.mjs so the main renderer stays under LOC budget.
+ * Does not import html-report.mjs (avoids a cycle).
+ */
+import {
+  detectDesignSmells,
+  summarizeDesignFitness,
+  buildPatternBetsFromSmells,
+} from './design-smells.mjs';
+import { summarizePilotLoop } from './pilot-loop.mjs';
+import { buildPostGreenNextAction } from './post-green-path.mjs';
+import { loadGoldenPattern, summarizeGoldenPattern } from './golden-pattern.mjs';
+import { collectAdoptionGaps } from './mcp-adoption.mjs';
+
+function esc(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/**
+ * Doctor-parity design depth + adoption for ark-check --report.
+ * @param {string} root
+ * @param {object} config
+ * @param {string[]} files
+ * @param {object} coverage
+ * @param {object[]} activeViolations
+ */
+export function buildReportDepthPayload(root, config, files, coverage, activeViolations = []) {
+  const designSmells = detectDesignSmells(root, config, files, coverage);
+  const designFitness = summarizeDesignFitness(designSmells, {
+    activeViolations: activeViolations.length,
+    governedPercent: coverage?.governed?.percent,
+    totalFiles: coverage?.governed?.totalFiles,
+  });
+  const postGreenPath = buildPostGreenNextAction(designFitness);
+  const patternBets = buildPatternBetsFromSmells(designSmells);
+  const pilotLoop = summarizePilotLoop({
+    designWeak: designFitness.designWeak,
+    patternBets,
+    designSmells,
+  });
+  const goldenPattern = summarizeGoldenPattern(loadGoldenPattern(root));
+  const adoption = collectAdoptionGaps(root, config, coverage);
+  return {
+    adoption,
+    designDepth: {
+      designFitness,
+      designSmells,
+      pilotLoop,
+      postGreenPath,
+      goldenPattern,
+    },
+  };
+}
+
+/** Write-path mode → human meaning (active host projection). */
+export function writePathModeHint(mode) {
+  switch (String(mode || '')) {
+    case 'repair':
+      return 'Hard write hook with repair payload — best co-pilot path for the active host.';
+    case 'reject-only':
+      return 'Hard write boundary without repair payload; edits can be blocked without guided re-entry.';
+    case 'mcp-only':
+      return 'Advisory MCP only — prepare-write/autoPatch available, no hard PreToolUse for this host.';
+    case 'none':
+      return 'No hard write boundary or advisory MCP for the active host (or host is unknown in this process).';
+    default:
+      return 'Session write-path capability for the active agent host.';
+  }
+}
+
+/**
+ * Configured hosts from writePath inventory (hard or advisory evidence on disk).
+ * @param {object|null|undefined} writePath
+ * @returns {string[]}
+ */
+export function inventoryConfiguredHosts(writePath) {
+  const hosts = writePath?.inventory?.hosts;
+  if (!hosts || typeof hosts !== 'object') return [];
+  return Object.entries(hosts)
+    .filter(([, rec]) => rec && rec.configured)
+    .map(([name]) => name);
+}
+
+/**
+ * Compact write-path line for the Adoption card.
+ * @param {object|null|undefined} writePath
+ */
+export function renderWritePathAdoptionBlock(writePath) {
+  if (!writePath || typeof writePath !== 'object') return '';
+  const mode = writePath.mode || 'none';
+  const host = writePath.activeHost || 'unknown';
+  const inv = inventoryConfiguredHosts(writePath);
+  const invLine =
+    inv.length > 0
+      ? `Inventory on disk: ${inv.map((h) => esc(h)).join(', ')}.`
+      : 'No host write gates found on disk yet.';
+  const unknownNote =
+    host === 'unknown' && inv.length > 0
+      ? ' Session host unknown (shell/CI) — inventory is still real; set ARK_ACTIVE_HOST or run from an agent for session-accurate mode.'
+      : '';
+  const gapNote = writePath.gap
+    ? ` Gap: <b>${esc(writePath.gap.id)}</b> — ${esc(writePath.gap.message || '')}`
+    : '';
+  // invLine / gapNote already include escaped user content; only plain strings go through esc().
+  return `<div class="write-path-block" title="${esc(writePathModeHint(mode))}">
+      <p class="dim" style="margin:.65rem 0 .2rem;font-size:.84rem">
+        <b>Write path</b> · active host <code>${esc(host)}</code>
+        · mode <code>${esc(mode)}</code>
+        ${writePath.hookRepair ? '· repair ✓' : writePath.hookPresent ? '· reject-only' : ''}
+        ${writePath.mcpPresent ? '· MCP ✓' : ''}
+      </p>
+      <p class="kpi-hint" style="max-width:none;margin:0">
+        ${esc(writePathModeHint(mode))} ${invLine}${esc(unknownNote)}${gapNote}
+      </p>
+    </div>`;
+}
+
+/** Fixed legend for baseline policy signals. */
+export function renderBaselineSignalLegend() {
+  return `<details class="baseline-legend" style="margin-top:.75rem">
+      <summary>Baseline policy signals (legend)</summary>
+      <ul class="senior-list" style="margin-top:.4rem">
+        <li><b>keep-empty</b> — ${esc(baselineLegendBody('keep-empty'))}</li>
+        <li><b>active-ratchet</b> — ${esc(baselineLegendBody('active-ratchet'))}</li>
+        <li><b>absent</b> — ${esc(baselineLegendBody('absent'))}</li>
+      </ul>
+    </details>`;
+}
+
+function baselineLegendBody(signal) {
+  switch (signal) {
+    case 'keep-empty':
+      return '`.ark-baseline.json` exists with 0 frozen keys; every violation is active (honest green).';
+    case 'active-ratchet':
+      return 'Known debt keys are frozen; new distinct violations still fail the check.';
+    case 'absent':
+      return 'No baseline file — all findings are active (or freeze not adopted).';
+    default:
+      return '';
+  }
+}
+
+/**
+ * Design-weak / Shape residual strip for the showcase report.
+ * Null HTML when there is nothing useful to show.
+ *
+ * @param {{
+ *   designFitness?: object|null,
+ *   designSmells?: object[],
+ *   pilotLoop?: object|null,
+ *   postGreenPath?: object|null,
+ *   goldenPattern?: object|null,
+ *   mode?: string,
+ * }} depth
+ */
+export function renderDesignDepthStrip(depth = {}) {
+  const fitness = depth.designFitness;
+  const smells = Array.isArray(depth.designSmells) ? depth.designSmells : [];
+  const designWeak = fitness?.designWeak === true;
+  if (!designWeak && smells.length === 0) return '';
+
+  const mode = String(depth.mode || '').toLowerCase();
+  const title = designWeak
+    ? mode === 'enforce'
+      ? 'ENFORCE · design-weak'
+      : `${(mode || 'edges').toUpperCase()} · design-weak`
+    : 'Design smells (edges still open)';
+  const lede = designWeak
+    ? 'Contract edges are clean, but lived design residual remains. This does not fail PASS — it blocks “healthy finished” until Shape work lands.'
+    : 'Design smells exist alongside open edge debt. Fix edges first; treat smells as Shape residual after green.';
+
+  const smellItems = smells
+    .slice(0, 6)
+    .map((s) => {
+      const outcome = s.outcome || s.message || s.id;
+      const evidence = (s.evidence || [])
+        .filter((e) => typeof e === 'string' && !e.startsWith('layer:') && !e.startsWith('layout:'))
+        .slice(0, 3);
+      const ev =
+        evidence.length > 0
+          ? ` <span class="dim">· ${evidence.map((e) => `<code>${esc(e)}</code>`).join(' ')}</span>`
+          : '';
+      return `<li><b>${esc(s.id)}</b> — ${esc(outcome)}${ev}</li>`;
+    })
+    .join('');
+
+  const pilot = depth.pilotLoop?.active && depth.pilotLoop?.nextPilot ? depth.pilotLoop.nextPilot : null;
+  const pilotHtml = pilot
+    ? `<div class="pilot-card">
+        <h3 style="margin-top:.85rem">Next pilot (one at a time)</h3>
+        <p class="dim" style="margin:.15rem 0 .4rem;font-size:.86rem">
+          Judgment only — never mechanical-safe · never multi-pilot batch
+        </p>
+        <ul class="senior-list">
+          <li><b>Smell</b> · <code>${esc(pilot.smellId || pilot.id || '—')}</code></li>
+          <li><b>Target</b> · <code>${esc(pilot.pilotTarget || pilot.pilot || '—')}</code></li>
+          ${
+            pilot.move || pilot.fix
+              ? `<li><b>Move</b> · ${esc(pilot.move || pilot.fix)}</li>`
+              : ''
+          }
+          ${
+            pilot.successSignal
+              ? `<li><b>Success</b> · ${esc(pilot.successSignal)}</li>`
+              : ''
+          }
+          ${
+            pilot.killSwitch
+              ? `<li><b>Kill-switch</b> · ${esc(pilot.killSwitch)}</li>`
+              : ''
+          }
+        </ul>
+      </div>`
+    : '';
+
+  const next =
+    depth.postGreenPath?.short ||
+    depth.postGreenPath?.action ||
+    (designWeak
+      ? '/ark-explore shape-focus → dual-plan B, then /ark-autopilot only with OK'
+      : null);
+  const nextHtml = next
+    ? `<p class="meta" style="margin-top:.75rem"><b>Primary next</b> · ${esc(next)}</p>`
+    : '';
+
+  const golden = depth.goldenPattern;
+  const goldenHtml =
+    golden && golden.present !== false && (golden.name || golden.norm)
+      ? `<p class="dim" style="margin-top:.5rem;font-size:.84rem">
+          Golden pattern (advisory for <b>new</b> code only):
+          <code>${esc(golden.name || 'pattern')}</code>
+          ${golden.norm ? ` — ${esc(golden.norm)}` : ''}
+          ${golden.examplePath ? ` · e.g. <code>${esc(golden.examplePath)}</code>` : ''}
+        </p>`
+      : designWeak
+        ? `<p class="dim" style="margin-top:.5rem;font-size:.84rem">
+            No <code>.ark/golden-pattern.json</code> yet — optional; helps agents place <b>new</b> code only.
+          </p>`
+        : '';
+
+  return `<div class="section card design-strip ${designWeak ? 'is-weak' : 'has-smells'}" id="design-depth">
+      <div class="design-head">
+        <span class="badge design" title="Shape residual — separate from PASS/FAIL edge honesty">${esc(title)}</span>
+        <span class="dim" style="font-size:.86rem">${designWeak ? 'Edges clean · residual remains' : 'Smells + open edges'}</span>
+      </div>
+      <p class="dim" style="margin:.55rem 0 .5rem;font-size:.9rem">${esc(lede)}</p>
+      ${smellItems ? `<ul class="senior-list">${smellItems}</ul>` : ''}
+      ${pilotHtml}
+      ${nextHtml}
+      ${goldenHtml}
+    </div>`;
+}
+
+/**
+ * Optional clean-depth note when edges + design are both healthy.
+ * Requires designFitness from a real sensor run (object). Null/undefined means
+ * depth was not computed — do not claim “OK” from missing data.
+ * @param {{ designFitness?: object|null, ok?: boolean, mode?: string }} depth
+ */
+export function renderDesignCleanNote(depth = {}) {
+  if (!depth.ok) return '';
+  // Sensors never ran (callers that omit designDepth) → no strip.
+  if (depth.designFitness == null || typeof depth.designFitness !== 'object') return '';
+  if (depth.designFitness.designWeak) return '';
+  if ((depth.designFitness.smellCount ?? 0) > 0) return '';
+  if (String(depth.mode || '').toLowerCase() !== 'enforce') return '';
+  return `<div class="section card design-strip is-clean" id="design-depth">
+      <div class="design-head">
+        <span class="badge design-ok" title="No deterministic design smells with clean edges">Design depth · OK</span>
+        <span class="dim" style="font-size:.86rem">No design-weak residual detected</span>
+      </div>
+      <p class="dim" style="margin:.45rem 0 0;font-size:.88rem">
+        Edges and deterministic design sensors agree. Keep placing new code on the golden path;
+        re-run doctor after large refactors.
+      </p>
+    </div>`;
+}