arkgate 4.3.0 → 4.5.0

package/CHANGELOG.md

@@ -5,14 +5,86 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
-## 4.3.0 — 2026-08-09 (prepared)
+## 4.5.0 — 2026-08-10
 
-**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.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: prepared in tree — not published on npm until OIDC publish + `npm view` succeed**
+(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: published**
+(`arkgate@4.4.0` on npm `latest`; 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 +130,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.4.0** is on npm `latest`. Tree is preparing **4.5.0** (session honesty + upgrade self-service) — see [4.5.0 notes](docs/releases/4.5.0.md) (Status: prepared until publish).
+> [4.5.0 notes](docs/releases/4.5.0.md) · [4.4.0](docs/releases/4.4.0.md) · [4.3.0](docs/releases/4.3.0.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,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) |
-| 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.4.0 on npm `latest`) | [docs/releases/4.4.0.md](docs/releases/4.4.0.md) · [CHANGELOG](CHANGELOG.md) |
+| Next prepare (4.5.0) | [docs/releases/4.5.0.md](docs/releases/4.5.0.md) (prepared — not published until npm verify) |
+| 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) |
 | Previous (4.1.0) | [docs/releases/4.1.0.md](docs/releases/4.1.0.md) |

package/bin/ark-check-runtime.mjs

@@ -1557,25 +1557,20 @@ 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
       : 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,8 +1583,43 @@ async function main() {
         frozenKeys: reportBaseline.exists ? reportBaseline.keys.size : 0,
         activeCount: activeViolations.length,
         activeBlockingCount: blockingViolations.length,
+        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,
@@ -1608,7 +1638,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/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/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.', '');