arkgate 4.3.0 → 4.4.0

package/CHANGELOG.md

@@ -5,14 +5,41 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
-## 4.3.0 — 2026-08-09 (prepared)
+## 4.4.0 — 2026-08-09
 
-**Minor** over 4.2.1. Phase ACS — agent contract surface: diagnostic code catalog, unified
-status snapshot, version-matched agent projection, Agent Skills packaging of the existing 13
-skills, stable finding refs, and maintainer placement A/B eval. **No required config migration.**
-Codex remains advisory at write time. Skills and AGENTS projection never enforce. Z09 / RB-11
-remain open. **Status: prepared** (`arkgate@4.3.0` not published yet; **4.2.1** remains on npm
-`latest` until publication).
+**Minor** over 4.3.0. Improvement compass (architecture lenses as a `notAScore` projection of
+existing sensors), doctor/HTML residual coaching, deeper skills + compact router for vibe-coder
+and full-AI workflows, and product-only public docs. **No required config migration.** Codex remains
+advisory at write time. Skills and AGENTS projection never enforce. **Status: prepared in tree —
+not published on npm until OIDC publish + `npm view` succeed** (see `docs/releases/4.4.0.md`).
+
+### Added
+
+- **Improvement compass:** doctor human section + `doctor.improvementCompass` JSON — closed set of
+  architecture **lenses** (SoC, DIP, domain alignment, …) with status `ok` / `residual` /
+  `not-instrumented` / `out-of-scope`, evidence refs, optional next action, capped `topResidual`,
+  always **`notAScore: true`**. Projected from existing smells, walls, cohesion, ArkRules, and
+  design-weak signals. Residual lenses never flip `valid`, strict-merge, or `goal.met`.
+  Out-of-scope locked for scalability, app security tooling, and full resilience. Type-only
+  placement debt (`failsStrict: false`) maps to **modularity** residual only (not coupling).
+- **Optional status slice:** thin `improvementCompass.topResidual` on the status manifest schema for
+  Tooling pass-through — **`ark status` does not compute lenses yet**; agents should read doctor.
+- **HTML report:** advisory section `data-advisory="improvementCompass"` (report parity with doctor).
+- **Skills + compact router:** same **13** skill names deepened for vibe-coder outcomes — compass
+  preflight, anti false-done, AI-easy placement cues, out-of-scope honesty, Completion **Compass**
+  bullet. Compact start router surfaces residual lenses and forbids “done” on green edges alone.
+- **Docs:** use / develop / agent-guide describe compass + Align/Stabilize/Shape in product language.
+
+**Freezes held:** no principle scores/ranks; no new skill names; no new ArkRules sensors; no LLM
+verdict; projection never enforces.
+
+## 4.3.0 — 2026-08-09
+
+**Minor** over 4.2.1. Agent contract surface: diagnostic code catalog, unified status snapshot,
+version-matched agent projection, Agent Skills packaging of the existing 13 skills, stable finding
+refs, and maintainer placement A/B eval. **No required config migration.** Codex remains advisory
+at write time. Skills and AGENTS projection never enforce. **Status: published**
+(`arkgate@4.3.0` on npm `latest`).
 
 ### Added
 
@@ -58,15 +85,14 @@ remain open. **Status: prepared** (`arkgate@4.3.0` not published yet; **4.2.1**
 ### Docs / claims (ACS08)
 
 - Claims matrix refreshed for 4.3.0 agent-contract statements (**0 Contradicted** on public
-  lanes). Release notes at `docs/releases/4.3.0.md` (**Status: prepared**). Public lanes name
-  the prepared candidate while npm `latest` remains **4.2.1** until Trusted Publishing.
+  lanes). Release notes at `docs/releases/4.3.0.md` (**Status: published**). npm `latest` is **4.3.0**.
 
 ## 4.2.1 — 2026-08-08 (published)
 
 **Patch** over 4.2.0. Next.js **16.3** field compatibility: root `proxy.ts` (Next 16 network-boundary
 rename of middleware) is scanned and classified; eval fixtures and release-surface pins track
 `next@16.3.0`. **No required config migration.** Codex remains advisory at write time.
-**Status: published** (`arkgate@4.2.1` on npm `latest`).
+**Status: published** (`arkgate@4.2.1`; superseded by 4.3.0 on `latest`).
 
 ### Fixed
 

package/README.md

@@ -16,9 +16,8 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.3.0** is prepared (agent contract surface: catalog, status, projection, skills packaging, finding refs);
-> **4.2.1** remains on npm `latest` until publication.
-> [4.3.0 candidate](docs/releases/4.3.0.md) · [4.2.1](docs/releases/4.2.1.md) · [4.2.0](docs/releases/4.2.0.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> **ArkGate 4.3.0** is on npm `latest`. Tree is preparing **4.4.0** (improvement compass) — see [4.4.0 notes](docs/releases/4.4.0.md) (Status: prepared until publish).
+> [4.4.0 notes](docs/releases/4.4.0.md) · [4.3.0](docs/releases/4.3.0.md) · [4.2.1](docs/releases/4.2.1.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
 
 ---
 
@@ -44,10 +43,13 @@ npx arkgate-check --doctor        # control plane: status light + primary next a
 ```
 
 That is the product. Doctor is the control plane — when stuck, do **primary next action #1**.
+Doctor also shows an **improvement compass** (architecture lenses such as separation of concerns and
+dependency inversion — **not a score**). Residual lenses mean Shape work may remain even when edges
+are green. Details: [use.md — Improvement compass](docs/use.md#improvement-compass-not-a-score).
 
 ```text
-start → doctor → day-to-day (place + gate)
-              ↘ optional /ark-autopilot after skill pack
+start → doctor (+ compass) → day-to-day (place + gate)
+                         ↘ optional /ark-autopilot after skill pack
 ```
 
 Aliases `ark` / `ark-check` / `ark-mcp` still work. npm / pnpm / yarn. No install lifecycle scripts.
@@ -206,8 +208,9 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Prepared candidate (4.3.0) | [docs/releases/4.3.0.md](docs/releases/4.3.0.md) · [CHANGELOG](CHANGELOG.md) |
-| Current published (4.2.1) | [docs/releases/4.2.1.md](docs/releases/4.2.1.md) |
+| Current release (4.3.0 on npm `latest`) | [docs/releases/4.3.0.md](docs/releases/4.3.0.md) · [CHANGELOG](CHANGELOG.md) |
+| Next prepare (4.4.0) | [docs/releases/4.4.0.md](docs/releases/4.4.0.md) (prepared — not published until npm verify) |
+| Prior (4.2.1) | [docs/releases/4.2.1.md](docs/releases/4.2.1.md) |
 | Previous (4.2.0) | [docs/releases/4.2.0.md](docs/releases/4.2.0.md) |
 | Previous (4.1.1) | [docs/releases/4.1.1.md](docs/releases/4.1.1.md) |
 | Previous (4.1.0) | [docs/releases/4.1.0.md](docs/releases/4.1.0.md) |

package/bin/ark-check-runtime.mjs

@@ -1576,6 +1576,14 @@ async function main() {
       : readJsonSafe(path.join(reportsDir(root), 'origin.json'));
     // Pass the same baseline split as doctor so productHonesty dirty-freeze matches.
     const reportBaseline = readBaseline(root, args.baseline || '.ark-baseline.json');
+    // Doctor parity for improvement compass: stale keys = baseline keys not in current occurrence set.
+    // Only when analysis is complete — partial scans under-count current keys and inflate false stale residual
+    // (same gate as doctor-plan: baselineStale: analysisComplete ? staleBaseline : null).
+    const reportOccurrenceKeys = baselineOccurrenceKeys(violations);
+    const reportCurrentKeys = new Set(reportOccurrenceKeys);
+    const reportBaselineStale = reportBaseline.exists
+      ? [...reportBaseline.keys].filter((key) => !reportCurrentKeys.has(key)).length
+      : 0;
     const { adoption: adoptionForReport, designDepth } = buildReportDepthPayload(
       root,
       config,
@@ -1588,6 +1596,7 @@ async function main() {
         frozenKeys: reportBaseline.exists ? reportBaseline.keys.size : 0,
         activeCount: activeViolations.length,
         activeBlockingCount: blockingViolations.length,
+        baselineStale: analysisComplete ? reportBaselineStale : null,
       }
     );
     const reportPayload = {
@@ -1608,7 +1617,13 @@ async function main() {
       originJustCreated: !existingOrigin,
       adoption: adoptionForReport,
       designDepth,
-      advisories: computeDoctorAdvisories(root, config, coverage, rules, files, ts, parseHealth),
+      advisories: {
+        ...computeDoctorAdvisories(root, config, coverage, rules, files, ts, parseHealth),
+        // Doctor parity: always emit improvement compass when doctor would (reportParity).
+        ...(designDepth?.improvementCompass
+          ? { improvementCompass: designDepth.improvementCompass }
+          : {}),
+      },
     };
     const html = args.beginner
       ? renderBeginnerHtmlReport(reportPayload)

package/bin/lib/agent-projection.mjs

@@ -148,7 +148,7 @@ export function buildAgentProjectionBody(facts) {
         '',
     ];
     if (profile === 'compact') {
-        lines.push('### Primary path', '', '1. Call `ark_identity` with `project.expectedRoot` at the exact project root; reuse root + `projectId` on Ark MCP calls.', '2. Read the contract with `ark_manifest` (same expectation). `ark://manifest` is compatibility-only / unverified.', '3. Place files inside configured layers; validate; run the check command above on violations — fix architecture, do not weaken the gate.', '', '### Contract layers (summary)', '', formatAgentProjectionLayers(layers), '');
+        lines.push('### Primary path', '', '1. Run doctor (`ark-check --doctor`) — status light + primary next action.', '2. Read the improvement compass (not a score). Name residual lenses in plain language; never “done” on green edges alone while residual remains.', '3. Call `ark_identity` with `project.expectedRoot` at the exact project root; reuse root + `projectId` on Ark MCP calls.', '4. Read the contract with `ark_manifest` (same expectation). `ark://manifest` is compatibility-only / unverified.', '5. Place files inside configured layers; validate; run the check command above on violations — fix architecture, do not weaken the gate.', '6. Single door: edges debt → fix; design-weak / residual shape lenses → map then guided apply with user OK.', '', '### Contract layers (summary)', '', formatAgentProjectionLayers(layers), '');
     }
     else {
         lines.push('### Contract layers', '', formatAgentProjectionLayers(layers), '', 'When creating a **new** kind of code that no layer covers, update `ark.config.json` first (`/ark-contract`), then place the file.', '', '### Diagnostic codes (short list)', '', formatAgentProjectionCatalogShortList(catalog, docsPath), '', '### Session truth', '', '- Machine snapshot: `ark status --json` (or MCP `ark_status`) — identity, activation honesty, last check, residual counts. **Not a score.**', '- Authoritative contract: `ark_manifest` after a matched `ark_identity` handshake.', '');

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

@@ -403,10 +403,16 @@ ${projectionBlock}
 
 **Primary path (do this):**
 
-1. Status anytime: \`${doctorCmd}\` — one status light, one next action (control plane).
-2. Before trusting MCP evidence: call \`ark_identity\` with \`project.expectedRoot\` set to this project's exact absolute root, then reuse that root plus the returned \`projectIdentity.projectId\` on every Ark MCP call. A descendant path is authoritative only with that matching id. Missing tool, non-\`matched\` binding, or wrong root means the process is stale: restart the host and use the local CLI meanwhile.
-3. Day to day: call \`ark_manifest\` with the same project expectation; place new files with \`ark_place\`; validate after edits; run \`${checkCmd}\`. The \`ark://manifest\` resource is compatibility-only and always unverified/non-authoritative. On a gate deny, fix the architecture — do not weaken the contract.
-4. If MCP is unavailable: inspect \`ark.config.json\` and run \`${checkCmd}\`.
+1. Status anytime: \`${doctorCmd}\` — one status light, one primary next action (control plane).
+2. Read the **Improvement compass** section (not a score). Name residual lenses in plain language when present (SoC, DIP, domain, …). Out-of-scope lenses (performance, app security tooling, full resilience) stay honest — do not invent Ark enforcement for them.
+3. Before trusting MCP evidence: call \`ark_identity\` with \`project.expectedRoot\` set to this project's exact absolute root, then reuse that root plus the returned \`projectIdentity.projectId\` on every Ark MCP call. A descendant path is authoritative only with that matching id. Missing tool, non-\`matched\` binding, or wrong root means the process is stale: restart the host and use the local CLI meanwhile.
+4. Day to day: call \`ark_manifest\` with the same project expectation; place new files with \`ark_place\`; validate after edits; run \`${checkCmd}\`. The \`ark://manifest\` resource is compatibility-only and always unverified/non-authoritative. On a gate deny, fix the architecture — do not weaken the contract.
+5. If MCP is unavailable: inspect \`ark.config.json\` and run \`${checkCmd}\`.
+
+**Single door when residual remains:**
+- **Edges debt** (import/capability violations) → fix with the gate / plan; skill pack only if doctor names a skill.
+- **Design-weak / residual shape lenses** (compass residual while edges may look green) → map first, then guided apply with user OK — never “you’re done” on green edges alone.
+- Empty plan A + residual lenses / design-weak → **not finished**.
 
 The selected host is \`${selectedHost}\`. Host registration and CI are installed with this file.
 This compact router is enough for normal feature work.
@@ -414,7 +420,7 @@ This compact router is enough for normal feature work.
 ## Expert depth (optional)
 
 Full \`/ark-*\` skills (including guided end-to-end \`/ark-autopilot\`) are **not** the default
-curriculum. Install them only when doctor top action #1 or a STOP handoff names a skill:
+curriculum. Install them only when doctor top action #1, residual compass, or a STOP handoff names a skill:
 
 \`${installSkills}\`
 `;

package/bin/lib/doctor-plan.mjs

@@ -62,6 +62,10 @@ import { computeDoctorAdvisories, printDoctorAdvisories } from './doctor-advisor
 import { ANALYSIS_COMPLETENESS, analysisIncompleteStatement, normalizeAnalysisCompleteness } from './analysis-completeness.mjs';
 import { designDeltaDoctorLines } from './design-delta.mjs';
 import { enforcementDoctorLines } from './enforcement-state.mjs';
+import {
+  buildDoctorImprovementCompass,
+  printImprovementCompassSection,
+} from './improvement-compass-doctor.mjs';
 
 const color = {
   green: (s) => `\x1b[32m${s}\x1b[0m`,
@@ -640,6 +644,23 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
         packageVersionTruth?.code === 'PACKAGE_PIN_SELF_HOST',
     });
 
+  // Improvement compass: projection only — never feeds ok/valid/goal.met.
+  const improvementCompass = buildDoctorImprovementCompass({
+    designSmells,
+    violations,
+    designWeak: designFitness.designWeak === true,
+    physicalCohesion: doctorAdvisories.physicalCohesion,
+    rulesUnderContract,
+    baselineExists: baseline.exists,
+    baselineStale: analysisComplete ? staleBaseline : null,
+    frozenResidual: baseline.exists ? baseline.keys.size : null,
+    dirtyBaselineRisk: productHonesty?.reasonIds?.includes?.('dirty-baseline') === true,
+    ungovernedDirCount: cov.suggestions?.length ?? 0,
+    emptyLayerCount: cov.emptyLayers?.length ?? 0,
+    goldenPatternPresent: goldenPattern.present === true,
+    arkRulesLoaded: rulesUnderContract?.active === true,
+  });
+
   if (asJson) {
     (options.writeJson ?? console.log)(
       JSON.stringify(
@@ -654,6 +675,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             // Path-correct ENFORCE can still be design-weak (P02).
             designFitness,
             designSmells,
+            // Improvement compass (lenses; notAScore; never a gate input).
+            improvementCompass,
             ...(options.designDelta ? { designDelta: options.designDelta } : {}),
             // Q01: primary next action when Shape residual dominates (null if not design-weak).
             postGreenPath,
@@ -846,6 +869,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     }
   }
 
+  printImprovementCompassSection(improvementCompass, { line, warn, ok, color });
+
   console.log('');
   console.log(color.bold('Design fitness'));
   if (designSmells.length === 0) {

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

@@ -10,6 +10,7 @@
 import { effectiveCapabilityDeny } from './analysis-engine.mjs';
 import { graphBlindSpotsHtml } from './graph-blind.mjs';
 import { formatRulesUnderContractHtml } from './rules-under-contract.mjs';
+import { primaryImprovementCompassNextAction } from './improvement-compass.mjs';
 
 // htmlEscape is injected by the caller (html-report.mjs) — importing it back
 // would be a dependency cycle, and the repo's own gate blocks that. The
@@ -247,10 +248,42 @@ function rulesUnderContractHtml(section) {
   return formatRulesUnderContractHtml(section, esc);
 }
 
+/** Improvement compass — advisory lenses only; never a score bar or gate input. */
+function improvementCompassHtml(compass) {
+  if (!compass || compass.notAScore !== true || !Array.isArray(compass.lenses)) return '';
+  const residual = Array.isArray(compass.topResidual) ? compass.topResidual : [];
+  const residualLine =
+    residual.length === 0
+      ? '<p class="muted">Residual: none on instrumented lenses (not a score — green edges ≠ finished design).</p>'
+      : `<p><span class="tag warn">residual</span> ${residual
+          .map((id) => {
+            const lens = compass.lenses.find((l) => l.id === id);
+            return `<code>${esc(id)}</code>${lens?.summary ? ` — ${esc(lens.summary)}` : ''}`;
+          })
+          .join('<br/>')}</p>`;
+  const oos = compass.lenses
+    .filter((l) => l && l.status === 'out-of-scope')
+    .map((l) => `<code>${esc(l.id)}</code>`)
+    .join(' · ');
+  // Same primary next as doctor human: severity-ordered topResidual, not lens-id order.
+  const next = primaryImprovementCompassNextAction(compass);
+  const nextLine = next
+    ? `<p class="muted">Next: <code>${esc(next.ref)}</code> — ${esc(next.summary)}</p>`
+    : '';
+  return `
+  <section class="section card" data-advisory="improvementCompass">
+    <h2>Improvement compass <span class="muted">(not a score — projection only; never changes the verdict)</span></h2>
+    ${residualLine}
+    <p class="muted">Out of scope (honest): ${oos || 'scalability · resilience · security'}</p>
+    ${nextLine}
+  </section>`;
+}
+
 export function renderAdvisorySections(advisories, escape) {
   if (!advisories || typeof advisories !== 'object') return '';
   if (typeof escape === 'function') esc = escape;
   return [
+    improvementCompassHtml(advisories.improvementCompass),
     contractHealthHtml(advisories.contractHealth),
     ambientStateHtml(advisories.ambientState),
     physicalCohesionHtml(advisories.physicalCohesion),

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

@@ -21,6 +21,8 @@ import {
 import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
 import { readBaseline, baselineOccurrenceKeys } from './violations.mjs';
 import { describePackageVersionDualTruth } from './field-install.mjs';
+import { buildDoctorImprovementCompass } from './improvement-compass-doctor.mjs';
+import { computePhysicalCohesion } from './physical-cohesion.mjs';
 
 function esc(value) {
   return String(value)
@@ -43,6 +45,7 @@ function esc(value) {
  *   frozenKeys?: number,
  *   activeCount?: number,
  *   activeBlockingCount?: number,
+ *   baselineStale?: number | null,
  * }} [baselineSplit] same numbers doctor uses (do not recompute from active-only list)
  */
 export function buildReportDepthPayload(
@@ -155,6 +158,26 @@ export function buildReportDepthPayload(
     primaryNextAction: postGreenPath?.action ?? dualTruthNext,
     activeBlockingViolations: activeBlockingCount,
   });
+  // Doctor parity: same physical-cohesion + baseline stale facts as runDoctor.
+  const physicalCohesion = computePhysicalCohesion(root, files);
+  const baselineStale =
+    typeof baselineSplit.baselineStale === 'number' ? baselineSplit.baselineStale : null;
+  // Improvement compass — same projection as doctor; notAScore; never a gate input.
+  const improvementCompass = buildDoctorImprovementCompass({
+    designSmells,
+    violations: activeViolations,
+    designWeak: designFitness.designWeak === true,
+    physicalCohesion,
+    rulesUnderContract,
+    baselineExists: baseline.exists || frozenKeys > 0,
+    baselineStale,
+    frozenResidual: frozenKeys,
+    dirtyBaselineRisk: productHonesty?.reasonIds?.includes?.('dirty-baseline') === true,
+    ungovernedDirCount: coverage?.suggestions?.length ?? 0,
+    emptyLayerCount: coverage?.emptyLayers?.length ?? 0,
+    goldenPatternPresent: goldenPattern.present === true,
+    arkRulesLoaded: rulesUnderContract?.active === true,
+  });
   return {
     adoption,
     designDepth: {
@@ -166,6 +189,7 @@ export function buildReportDepthPayload(
       // P0-B / P1-M — folded into designDepth so --report stays a single payload.
       productHonesty,
       mergePlanes: rulesUnderContract?.mergePlanes ?? null,
+      improvementCompass,
     },
   };
 }

package/bin/lib/improvement-compass-doctor.mjs

@@ -0,0 +1,106 @@
+/**
+ * Doctor adapter for the Domain improvement compass (notAScore projection).
+ * Keeps doctor-plan.mjs inside its module budget; pure assembly only.
+ */
+import {
+  buildImprovementCompass,
+  formatImprovementCompassDoctorLines,
+  primaryImprovementCompassNextAction,
+} from './improvement-compass.mjs';
+
+/**
+ * @param {{
+ *   designSmells?: object[],
+ *   violations?: object[],
+ *   designWeak?: boolean,
+ *   physicalCohesion?: { findings?: object[] } | null,
+ *   rulesUnderContract?: object | null,
+ *   baselineExists?: boolean,
+ *   baselineStale?: number | null,
+ *   frozenResidual?: number | null,
+ *   dirtyBaselineRisk?: boolean,
+ *   ungovernedDirCount?: number,
+ *   emptyLayerCount?: number,
+ *   goldenPatternPresent?: boolean,
+ *   arkRulesLoaded?: boolean,
+ * }} input
+ */
+export function buildDoctorImprovementCompass(input = {}) {
+  const violations = Array.isArray(input.violations) ? input.violations : [];
+  const ruleId = (v) => String(v?.ruleId ?? v?.code ?? '');
+
+  let cycleCount = 0;
+  let peerIsolationCount = 0;
+  let pureOrCapabilityResidual = 0;
+  let forbiddenGlobalResidual = 0;
+  let arkRulesStructureResidual = 0;
+
+  for (const v of violations) {
+    const id = ruleId(v).toUpperCase();
+    if (!id) continue;
+    if (id.includes('CYCLE') || id === 'CIRCULAR_DEPENDENCY') cycleCount += 1;
+    if (id.includes('PEER_ISOLATION')) peerIsolationCount += 1;
+    if (id === 'CAPABILITY_VIOLATION') pureOrCapabilityResidual += 1;
+    if (id === 'FORBIDDEN_GLOBAL' || id.startsWith('FORBIDDEN_')) forbiddenGlobalResidual += 1;
+    if (id.startsWith('ARKRULE_') || id === 'INVARIANT_UNCOVERED') arkRulesStructureResidual += 1;
+  }
+
+  const pcFindings = input.physicalCohesion?.findings;
+  const physicalCohesionFindingCount = Array.isArray(pcFindings) ? pcFindings.length : 0;
+
+  const arkRulesLoaded =
+    input.arkRulesLoaded === true ||
+    input.rulesUnderContract?.active === true ||
+    (typeof input.rulesUnderContract?.structureRules === 'number' &&
+      input.rulesUnderContract.structureRules > 0);
+
+  return buildImprovementCompass({
+    designSmells: Array.isArray(input.designSmells) ? input.designSmells : [],
+    violations: violations.map((v) => ({
+      ruleId: ruleId(v) || undefined,
+      message: typeof v?.message === 'string' ? v.message : undefined,
+      file: typeof v?.file === 'string' ? v.file : typeof v?.path === 'string' ? v.path : undefined,
+      fromLayer: v?.fromLayer,
+      toLayer: v?.toLayer,
+      failsStrict: v?.failsStrict,
+      typeOnly: v?.typeOnly === true || v?.namedBindingsTypeOnly === true || undefined,
+    })),
+    cycleCount,
+    peerIsolationCount,
+    physicalCohesionFindingCount,
+    arkRulesLoaded,
+    arkRulesStructureResidual,
+    designWeak: input.designWeak === true,
+    baselineExists: input.baselineExists === true,
+    baselineStale: input.baselineStale ?? null,
+    frozenResidual: input.frozenResidual ?? null,
+    dirtyBaselineRisk: input.dirtyBaselineRisk === true,
+    pureOrCapabilityResidual,
+    forbiddenGlobalResidual,
+    ungovernedDirCount: Number(input.ungovernedDirCount) || 0,
+    emptyLayerCount: Number(input.emptyLayerCount) || 0,
+    goldenPatternPresent: input.goldenPatternPresent === true,
+    // Doctor path is TypeScript-oriented (ArkGate product surface).
+    stackKind: 'typescript',
+  });
+}
+
+export {
+  formatImprovementCompassDoctorLines,
+  primaryImprovementCompassNextAction,
+};
+
+/**
+ * Human doctor section (never a score bar).
+ * @param {import('./improvement-compass.mjs').ImprovementCompass} compass
+ * @param {{ line: Function, warn: string, ok: string, color: { bold: Function } }} io
+ */
+export function printImprovementCompassSection(compass, io) {
+  const { line, warn, ok, color } = io;
+  console.log('');
+  console.log(color.bold('Improvement compass (not a score)'));
+  const mark = compass.topResidual.length > 0 ? warn : ok;
+  for (const text of formatImprovementCompassDoctorLines(compass)) {
+    line(mark, text);
+  }
+}