arkgate 4.4.0 → 4.5.5

package/CHANGELOG.md

@@ -5,13 +5,82 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.5.5 — 2026-08-11
+
+**Patch** over **4.5.0**. Deep-module coach train plus upgrade **suggested improvements /
+what’s new** so consumers know what to try after install. **No required config migration.**
+No new skill names, sensors, or scores. Freezes held.
+
+**Status: prepared** (implementation only; not yet on npm `latest` — remains `4.5.0` until
+the publication checklist completes).
+
+### Added
+
+- **Deep-module coach (advisory):** `ark-check --doctor` JSON `doctor.deepModuleCoach` + human
+  section + HTML `data-advisory="deepModuleCoach"`. Hot paths from bounded git history
+  (`unavailable` + empty when history missing — never invent). Deepening candidates projected
+  only from existing design smells / physical cohesion / pilot / residual compass evidence —
+  empty when no evidence. Always `notAScore: true`; never flips gate verdicts. Pure helper
+  `buildDeepeningCandidates` (+ CLI gen mirror).
+- **Product voice + skills:** lexicon for depth / seam / deletion test / test-at-public-interface
+  / domain glossary / two-axis done. Existing skills (explore, think, place, fix, loop, adopt)
+  deepened; agent-skills 1:1. Compact router + agent-guide **two-axis done** (Enforce green ≠
+  feature done). Remediation port/inject `nextAction` prose includes test at the public interface.
+- **Upgrade suggested improvements / what’s new:** `ark upgrade` JSON `whatsNew` + human block
+  lists concrete try/inspect actions (deep-module coach, improvement compass, session/status
+  honesty, two-axis done, self-service honesty). Always `notAScore`; never a gate input.
+
+## 4.5.0 — 2026-08-10
+
+**Minor** over 4.4.0. Session control-plane honesty (status/MCP improvement compass with explicit
+modes), domain module fitness (split oversized pure modules), selective pure verification ratchet,
+self-service upgrade activation honesty, and a short session recipe in product docs. **No required
+config migration.** Codex remains advisory at write time. Skills and AGENTS projection never
+enforce. **Status: published** (`arkgate@4.5.0` on npm `latest`; see `docs/releases/4.5.0.md`).
+
+### Added
+
+- **Status / MCP improvement compass honesty:** `ark status --json` and MCP `ark_status` always
+  project `improvementCompass` with explicit mode `full` \| `subset` \| `unavailable`, residual
+  lens ids, and `notAScore: true`. Incomplete or missing session facts never invent green residual.
+  When mode is `full`, residual ids are a subset of doctor residual for the same facts (report
+  snapshots store the thin slice). Residual never flips `valid` / strict-merge / `goal.met`.
+  Root helpers: `projectStatusImprovementCompass`, `STATUS_COMPASS_MODES`.
+- **Session recipe (product docs):** identity bind → `ark status` → act on residual / `findingRef`;
+  run doctor when status compass mode is not `full`. Documented in use / agent-guide / develop —
+  no new skill names.
+- **Managed upgrade self-service honesty:** `ark upgrade [--json]` surfaces `selfService` with
+  per-host write-path activation labels (`hard` \| `advisory` \| `unavailable`) and customized
+  content-identity preserve (`customizedPaths` / `customizedContentPreserved`). Soft hosts never
+  hard; upgrade never invents `hardWriteActive` from disk alone. Always `notAScore: true`. Human
+  output: “Self-service honesty” lines.
+
+### Changed
+
+- **Domain module fitness:** pure Domain `improvementCompass` monolith split into
+  `improvementCompassTypes` + `improvementCompassMap` + facade `improvementCompass` (public
+  re-exports unchanged). All three tracked in `check:module-budgets`; over-ceiling domain modules
+  require a behavior-preserving split — raising max alone is not done. CLI pure mirrors:
+  `improvement-compass-types.mjs`, `improvement-compass-map.mjs`, `improvement-compass.mjs`.
+- **Critical pure verification ratchet:** selective verification islands on
+  `layerMatch` peerIsolation fail-closed (missing paths/slices),
+  `policyDeltaAcknowledgementMatches` (hash + finding-id set), and
+  `canPromoteInvariant` promote honesty. Property suites under `tests/property/` plus unit fixtures;
+  Stryker mutate ranges + critical groups `peer-isolation-fail-closed`,
+  `policy-delta-ack-match`, `invariant-promote-honesty`. Mutation remains cost-gated to full-matrix
+  CI / publish (`npm run test:mutation` via `test:confidence`) — **not** a whole-repo mutation claim.
+  Strict semantics unchanged.
+
+**Freezes held:** no principle scores/ranks; no new skill names; no new ArkRules sensors; no LLM
+verdict; projection never enforces; no false hard-write for soft hosts.
+
 ## 4.4.0 — 2026-08-09
 
 **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`).
+advisory at write time. Skills and AGENTS projection never enforce. **Status: published**
+(`arkgate@4.4.0` on npm `latest`; see `docs/releases/4.4.0.md`).
 
 ### Added
 

package/README.md

@@ -16,8 +16,9 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **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)
+> **ArkGate 4.5.5** is **prepared** (deep-module coach + upgrade what’s new). npm `latest` remains
+> **4.5.0** until publish. [4.5.5 notes](docs/releases/4.5.5.md) · [4.5.0](docs/releases/4.5.0.md) ·
+> [4.4.0](docs/releases/4.4.0.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
 
 ---
 
@@ -208,8 +209,10 @@ 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) |
-| 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) |
+| Prepared (4.5.5) | [docs/releases/4.5.5.md](docs/releases/4.5.5.md) · [CHANGELOG](CHANGELOG.md) |
+| Current published (4.5.0 on npm `latest`) | [docs/releases/4.5.0.md](docs/releases/4.5.0.md) |
+| Prior (4.4.0) | [docs/releases/4.4.0.md](docs/releases/4.4.0.md) |
+| Prior (4.3.0) | [docs/releases/4.3.0.md](docs/releases/4.3.0.md) |
 | 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) |

package/bin/ark-check-runtime.mjs

@@ -1557,19 +1557,6 @@ async function main() {
       enforcement: enforcementForReport,
       config,
     });
-    const currentSnapshot = buildReportSnapshot({
-      root,
-      config,
-      coverage,
-      violations: activeViolations,
-      ok,
-      suppressed: suppressed.length,
-      version: arkPackageVersion(),
-      fileCountByLayer,
-      enforcement: enforcementForReport,
-      score: fitness.score,
-      mode: fitness.mode,
-    });
     // Origin is read before archive so the HTML can show "just created" vs deltas.
     const existingOrigin = args.resetOrigin
       ? null
@@ -1599,6 +1586,40 @@ async function main() {
         baselineStale: analysisComplete ? reportBaselineStale : null,
       }
     );
+    // DF02 — thin status compass on report snapshot so `ark status` residual ⊆ doctor.
+    const reportCompass =
+      designDepth?.improvementCompass && designDepth.improvementCompass.notAScore === true
+        ? {
+            schemaVersion: '1.0',
+            notAScore: true,
+            mode: analysisComplete ? 'full' : 'subset',
+            topResidual: Array.isArray(designDepth.improvementCompass.topResidual)
+              ? designDepth.improvementCompass.topResidual
+              : [],
+            factsSource: 'report-snapshot',
+            ...(analysisComplete
+              ? {}
+              : {
+                  reasonCode: 'FACTS_PARTIAL',
+                  reason:
+                    'Report analysis was incomplete — status compass is a subset; re-run doctor/report for full residual.',
+                }),
+          }
+        : null;
+    const currentSnapshot = buildReportSnapshot({
+      root,
+      config,
+      coverage,
+      violations: activeViolations,
+      ok,
+      suppressed: suppressed.length,
+      version: arkPackageVersion(),
+      fileCountByLayer,
+      enforcement: enforcementForReport,
+      score: fitness.score,
+      mode: fitness.mode,
+      improvementCompass: reportCompass,
+    });
     const reportPayload = {
       root,
       config,
@@ -1623,6 +1644,10 @@ async function main() {
         ...(designDepth?.improvementCompass
           ? { improvementCompass: designDepth.improvementCompass }
           : {}),
+        // Doctor parity: deep-module coach advisory (hot paths + deepening; notAScore).
+        ...(designDepth?.deepModuleCoach
+          ? { deepModuleCoach: designDepth.deepModuleCoach }
+          : {}),
       },
     };
     const html = args.beginner

package/bin/ark-layer-match.mjs

@@ -258,6 +258,21 @@ function resolveSliceFolders(rule, layerName, layers) {
     const layer = (layers ?? []).find((l) => l.name === layerName);
     return inferSliceFoldersFromPatterns(layer?.patterns);
 }
+/**
+ * PeerIsolation deny decision given resolved path/slice evidence (DF04 pure core).
+ *
+ * Fail-closed: missing path, no classifiable folders, or unclassifiable either
+ * side → deny. Same-slice → allow (return false). Cross-slice → deny.
+ */
+export function peerIsolationMustDeny(input) {
+    if (!input.fromPath || !input.toPath)
+        return true;
+    if (input.folderCount <= 0)
+        return true;
+    if (!input.fromSlice || !input.toSlice)
+        return true;
+    return input.fromSlice !== input.toSlice;
+}
 /**
  * Find the first denying rule for a layer edge.
  *
@@ -279,20 +294,18 @@ export function findDeniedEdgeRule(rules, from, to, options) {
         if (rule.peerIsolation) {
             const fromPath = options?.fromPath;
             const toPath = options?.toPath;
-            // Isolation is active: without both paths we cannot prove same-slice.
-            if (!fromPath || !toPath)
-                return rule;
             const folders = resolveSliceFolders(rule, from, options?.layers);
-            // Configured isolation without classifiable folders cannot allow.
-            if (folders.length === 0)
-                return rule;
-            const fromSlice = sliceIdForPath(fromPath, folders);
-            const toSlice = sliceIdForPath(toPath, folders);
-            // Unclassifiable either side: cannot prove same-slice → deny.
-            if (!fromSlice || !toSlice)
-                return rule;
-            if (fromSlice !== toSlice)
+            const fromSlice = fromPath && toPath ? sliceIdForPath(fromPath, folders) : undefined;
+            const toSlice = fromPath && toPath ? sliceIdForPath(toPath, folders) : undefined;
+            if (peerIsolationMustDeny({
+                fromPath,
+                toPath,
+                folderCount: folders.length,
+                fromSlice,
+                toSlice,
+            })) {
                 return rule;
+            }
             continue; // same slice: this peerIsolation rule does not deny
         }
         // Classic deny — same-layer always allowed without peerIsolation

package/bin/lib/adapter-contract.mjs

@@ -82,18 +82,18 @@ function nextActionForDiagnostic(ruleId, evidence, violation) {
             return 'Move the referenced type to a mutually allowed layer, use `import type`, then preflight again.';
         }
         if (violation.peerIsolation === true) {
-            return 'Extract the shared dependency to a shared layer, then preflight again.';
+            return 'Extract the shared dependency to a shared layer, test at the public interface, then preflight again.';
         }
-        return `Define a port in ${evidence.fromLayer ?? 'the source layer'}, inject the ${evidence.toLayer ?? 'outer-layer'} implementation, then preflight again.`;
+        return `Define a port in ${evidence.fromLayer ?? 'the source layer'}, inject the ${evidence.toLayer ?? 'outer-layer'} implementation, test at the public interface, then preflight again.`;
     }
     if (ruleId === 'FORBIDDEN_GLOBAL') {
-        return `Inject ${evidence.target ?? 'the capability'} through a port, then preflight again.`;
+        return `Inject ${evidence.target ?? 'the capability'} through a port, test at the public interface, then preflight again.`;
     }
     if (ruleId === 'CAPABILITY_VIOLATION') {
-        return `Define a ${text(violation.capability) ?? 'capability'} port in ${evidence.fromLayer ?? 'the walled layer'}, bind the implementation outside it, then preflight again.`;
+        return `Define a ${text(violation.capability) ?? 'capability'} port in ${evidence.fromLayer ?? 'the walled layer'}, bind the implementation outside it, test at the public interface, then preflight again.`;
     }
     if (ruleId === 'CIRCULAR_DEPENDENCY') {
-        return 'Extract the shared dependency into a third module, then preflight again.';
+        return 'Extract the shared dependency into a third module, test at the public interface, then preflight again.';
     }
     if (ruleId === 'RAW_EVENT_PUBLISH')
         return 'Publish through a registered intent creator, then run Ark again.';