arkgate 4.8.19 → 4.8.20

package/CHANGELOG.md

@@ -96,6 +96,107 @@ in the immutable pre-2.0 archive linked below.
   Existing configs keep whatever URL they already have. Editor completion
   matches the 4.x line you just installed.
 
+## 4.8.20 — 2026-09-25
+
+**Patch** over **4.8.19**. Daily accumulate (2026-09-25 ART) of the ships
+that landed after 4.8.19 published: `coverage.symbol` is a non-test
+declaration
+([#301](https://github.com/pedroknigge/arkgate/pull/301) /
+[#291](https://github.com/pedroknigge/arkgate/issues/291)), reshape pilot
+stays in the source layer and slice
+([#299](https://github.com/pedroknigge/arkgate/pull/299) /
+[#295](https://github.com/pedroknigge/arkgate/issues/295)),
+physical-cohesion residual clears finished and elegant
+([#302](https://github.com/pedroknigge/arkgate/pull/302) /
+[#296](https://github.com/pedroknigge/arkgate/issues/296)), anchored
+starred `sliceFolders`
+([#300](https://github.com/pedroknigge/arkgate/pull/300) /
+[#294](https://github.com/pedroknigge/arkgate/issues/294)), shared roots
+cannot import a slice when opted in
+([#303](https://github.com/pedroknigge/arkgate/pull/303) /
+[#297](https://github.com/pedroknigge/arkgate/issues/297)), pnpm Age
+install-fail recovery
+([#293](https://github.com/pedroknigge/arkgate/pull/293) /
+[#292](https://github.com/pedroknigge/arkgate/issues/292)), vitest 4.1.11
+([#298](https://github.com/pedroknigge/arkgate/pull/298)), Dependabot
+vitest 5 ignore
+([#304](https://github.com/pedroknigge/arkgate/pull/304)), and docs
+([#244](https://github.com/pedroknigge/arkgate/pull/244),
+[#234](https://github.com/pedroknigge/arkgate/pull/234)).
+**Write. Check. Ship.** **No required config migration.** No
+`schemaVersion` bump. Does not close `K01` / `Z09`. This mother
+`ark.config.json` still does **not** turn `arkOrder` on.
+
+**Status: published** (npm `latest` is **4.8.20**).
+
+### Changed
+- This is a behavior change. Some repos that are green today will turn red
+  when `coverage.symbol` only appeared in tests or imports.
+  `symbolEvidenceFile` is the non-test file that declares the symbol.
+  Discard counters (`depthLimited`, the per-file byte cap, and the other
+  existing reasons) are printed on green doctor and `--rules-inventory`
+  output too; the depth and byte caps themselves stay internal
+  ([#301](https://github.com/pedroknigge/arkgate/pull/301) /
+  [#291](https://github.com/pedroknigge/arkgate/issues/291)).
+- `sliceFolders` accepts a starred prefix (`lib/features/*/*`), anchored
+  like `sharedRoots`. The slice id is the directories the stars bind
+  (`lib/features/projects/rfi`). A star never binds a filename; a file
+  directly under that prefix stays in the last directory
+  (`lib/features/projects`). Bare `sliceFolders` names no longer treat a
+  filename as the slice child segment.
+  `src/components/features/projects/rfi-status-pill.tsx` with `["projects"]`
+  is not a slice. Bare names under `src/lib/features` behave exactly as
+  before: `src/lib/features/projects/rfi/x.ts` with `["features"]` stays
+  `features/projects` (a regression test covers it)
+  ([#300](https://github.com/pedroknigge/arkgate/pull/300) /
+  [#294](https://github.com/pedroknigge/arkgate/issues/294)).
+
+### Fixed
+- Reshape pilot destinations stay in the source file's layer and slice. A
+  proposal that would leave both is withheld instead of pointing at
+  `src/features/`
+  ([#299](https://github.com/pedroknigge/arkgate/pull/299) /
+  [#295](https://github.com/pedroknigge/arkgate/issues/295)).
+- Doctor no longer calls the tree finished or elegant while a
+  physical-cohesion finding is still unsuppressed. The gate verdict is
+  unchanged, and the reshape card stays one judgment
+  ([#302](https://github.com/pedroknigge/arkgate/pull/302) /
+  [#296](https://github.com/pedroknigge/arkgate/issues/296)).
+- A `peerIsolation` rule may set `sharedImportsSlice` to `"deny"`. A
+  declared shared root then may not import a slice
+  (`shared root … → slice …`). The default stays off, so current walls
+  stay green. A slice importing a shared root stays allowed.
+  `allowedCrossSlice` does not excuse this hop. Doctor lists shared-root
+  → slice bridges even when the flag is off. A green run still says the
+  wall is direct-only
+  ([#303](https://github.com/pedroknigge/arkgate/pull/303) /
+  [#297](https://github.com/pedroknigge/arkgate/issues/297)).
+- Age-gated `start --apply` install failure no longer reprints the same
+  `pnpm add` as the primary next step. Recovery names pnpm Age, leads
+  with `npx --package=arkgate@<pin> arkgate-check --doctor`, and says
+  `minimumReleaseAgeExclude` must live in pnpm config or
+  `pnpm-workspace.yaml` (a CLI flag is not enough)
+  ([#293](https://github.com/pedroknigge/arkgate/pull/293) /
+  [#292](https://github.com/pedroknigge/arkgate/issues/292)).
+
+### Dependencies
+- Dev dependency `vitest` and `@vitest/coverage-v8` are on 4.1.11, which
+  pulls `@vitest/mocker@4.1.11` and closes
+  [GHSA-82fw-gwwq-j7x9](https://github.com/vitest-dev/vitest/security/advisories/GHSA-82fw-gwwq-j7x9)
+  (moderate path traversal via redirect mocks). Vitest 4's V8 coverage
+  provider remaps with AST analysis, so the same suite reports a larger
+  branch denominator; coverage floors moved to just under those measured
+  numbers. No tests were removed
+  ([#298](https://github.com/pedroknigge/arkgate/pull/298)).
+- Dependabot ignores vitest 5 (`vitest`, `@vitest/coverage-v8`, and
+  `@vitest/mocker` at `>= 5.0.0`) until Node 22.12+ is the floor.
+  Version-update pull requests stay off; the cooldown is 7 days
+  ([#304](https://github.com/pedroknigge/arkgate/pull/304)).
+- Docs: anonymized live dogfood sales stats
+  ([#244](https://github.com/pedroknigge/arkgate/pull/244)); `UC01` marked
+  done after [#233](https://github.com/pedroknigge/arkgate/pull/233)
+  ([#234](https://github.com/pedroknigge/arkgate/pull/234)).
+
 ## 4.8.19 — 2026-09-20
 
 **Patch** over **4.8.18**. Daily accumulate (2026-09-20 ART) of the five

package/README.md

@@ -39,7 +39,7 @@ Works with Cursor, Claude, Codex, and Grok.
 
 </div>
 
-> **ArkGate 4.8.19** is on npm `latest`.
+> **ArkGate 4.8.20** is on npm `latest`.
 > Write. Check. Ship. Adopted = required GitHub
 > status running `arkgate-check --strict-merge`, or an explicit `advisory-only` stance.
 > Status is compact (`arkgate-check --doctor`; `--all` for Details). Optional **ArkRun**
@@ -47,7 +47,7 @@ Works with Cursor, Claude, Codex, and Grok.
 > (`arkgate/order`) stops rewriting a big product choice — like the billing plan —
 > as if it were a seat count. Change those choices through a valve, not a generic update.
 > `@arkgate/runtime` is deprecated.
-> [4.8.19](CHANGELOG.md) · [4.8.11](docs/releases/4.8.11.md) · [4.8.10](docs/releases/4.8.10.md) · [4.8.9](docs/releases/4.8.9.md) · [4.8.8](docs/releases/4.8.8.md) · [4.8.7](docs/releases/4.8.7.md) · [4.8.6](docs/releases/4.8.6.md) · [4.8.5](docs/releases/4.8.5.md) · [4.8.4](docs/releases/4.8.4.md) · [4.8.3](docs/releases/4.8.3.md) · [4.8.2](docs/releases/4.8.2.md) · [4.8.1](docs/releases/4.8.1.md) · [4.8.0](docs/releases/4.8.0.md) · [Docs hub](docs/README.md) · [Voice](docs/product-voice.md)
+> [4.8.20](CHANGELOG.md) · [4.8.11](docs/releases/4.8.11.md) · [4.8.10](docs/releases/4.8.10.md) · [4.8.9](docs/releases/4.8.9.md) · [4.8.8](docs/releases/4.8.8.md) · [4.8.7](docs/releases/4.8.7.md) · [4.8.6](docs/releases/4.8.6.md) · [4.8.5](docs/releases/4.8.5.md) · [4.8.4](docs/releases/4.8.4.md) · [4.8.3](docs/releases/4.8.3.md) · [4.8.2](docs/releases/4.8.2.md) · [4.8.1](docs/releases/4.8.1.md) · [4.8.0](docs/releases/4.8.0.md) · [Docs hub](docs/README.md) · [Voice](docs/product-voice.md)
 
 ---
 
@@ -72,7 +72,7 @@ npx --package=arkgate arkgate-check --doctor        # status — one next step
 npx --package=arkgate arkgate-check --doctor --all  # full details
 ```
 
-`start --apply` pins arkgate with this repo's package manager (`pnpm add -w` / `yarn add -W` at a workspace root). Do not run `npm install -D arkgate` at a `workspace:*` root — npm rejects that protocol. After a local install, `npx arkgate-check --doctor` also works. `arkgate-check` is a command in the `arkgate` package, not its own npm package.
+`start --apply` pins arkgate with this repo's package manager (`pnpm add -w` / `yarn add -W` at a workspace root). Do not run `npm install -D arkgate` at a `workspace:*` root — npm rejects that protocol. After a local install, `npx arkgate-check --doctor` also works. `arkgate-check` is a command in the `arkgate` package, not its own npm package. If pnpm Age (`minimumReleaseAge`) blocks a brand-new release, keep using `npx --package=arkgate@<version>` — do not re-run the same add. Put arkgate on `minimumReleaseAgeExclude` in pnpm config or `pnpm-workspace.yaml` (a CLI flag is not enough), or wait until the package is mature.
 
 `start --apply` refuses when projected governed coverage is below 50% or
 shape confidence is weak (below 0.6 with coverage under 80%), or when the
@@ -346,7 +346,7 @@ Compact starters leave the extra off. Details: [ArkOrder](docs/arkorder.md).
 | 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 published (4.8.19 on npm `latest`) | [CHANGELOG](CHANGELOG.md) |
+| Current published (4.8.20 on npm `latest`) | [CHANGELOG](CHANGELOG.md) |
 | Prior published (4.8.11) | [docs/releases/4.8.11.md](docs/releases/4.8.11.md) · [CHANGELOG](CHANGELOG.md) |
 | Prior published (4.8.10) | [docs/releases/4.8.10.md](docs/releases/4.8.10.md) · [CHANGELOG](CHANGELOG.md) |
 | Prior published (4.8.9) | [docs/releases/4.8.9.md](docs/releases/4.8.9.md) · [CHANGELOG](CHANGELOG.md) |

package/bin/ark-check-runtime.mjs

@@ -1673,6 +1673,27 @@ async function main() {
       inventory.candidates[0] != null
         ? inventoryToExtractionCard(inventory.candidates[0])
         : null;
+    let evidenceLines = [];
+    let coverageEvidence = null;
+    if (config.arkRules && Object.keys(config.arkRules).length > 0) {
+      try {
+        const { summarizeRulesUnderContract, formatArkRulesEvidenceLines } = await import(
+          './lib/rules-under-contract.mjs'
+        );
+        const section = summarizeRulesUnderContract(root, config, {
+          files: files.map((file) => ({ path: normalize(path.relative(root, file)) })),
+        });
+        evidenceLines = formatArkRulesEvidenceLines(section);
+        if (section.active === true) {
+          coverageEvidence = {
+            symbolEvidence: section.symbolEvidence ?? [],
+            discarded: section.coverageStats?.discarded ?? null,
+          };
+        }
+      } catch {
+        /* inventory still useful when coverage cannot be read */
+      }
+    }
     const payload = {
       rulesInventory: inventory,
       rulesMigration: {
@@ -1682,6 +1703,7 @@ async function main() {
         notAScore: true,
       },
       nextPilot: nextPilot,
+      ...(coverageEvidence ? { coverageEvidence } : {}),
     };
     if (args.json) {
       console.log(JSON.stringify(payload, null, 2));
@@ -1695,6 +1717,7 @@ async function main() {
       if (nextPilot) {
         console.log(`Next extraction pilot: ${nextPilot.pilot} → ${nextPilot.pilotTarget}`);
       }
+      for (const line of evidenceLines) console.log(line);
     }
     process.exitCode = 0;
     return;

package/bin/ark-layer-match.mjs

@@ -215,6 +215,14 @@ export function layerForRelativePath(relPath, layers) {
  * Includes the parent folder so `features/auth` ≠ `modules/auth`.
  * Identity is case-normalized for portable results across filesystems.
  * `src/features/auth/api.ts` + folders `["features"]` → `"features/auth"`.
+ *
+ * A bare name stays that unanchored one-segment match. The child segment is
+ * never the filename, so a flat file under the parent is not its own slice.
+ * A starred prefix (`lib/features` plus one star per extra directory) reuses
+ * the shared-root anchor: it must sit at offset 0, or at offset 1 after `src/`
+ * or `app/`. The slice id is the concrete directories the stars bind. A star
+ * never binds the filename; a file directly under the last bound directory
+ * keeps that directory as its slice.
  */
 export function sliceIdForPath(relPath, sliceFolders) {
     if (!sliceFolders?.length)
@@ -222,11 +230,87 @@ export function sliceIdForPath(relPath, sliceFolders) {
     const parts = String(relPath)
         .split(/[/\\]/)
         .filter(Boolean);
-    const folders = new Set(sliceFolders.map((s) => String(s).toLowerCase()));
-    for (let i = 0; i < parts.length - 1; i += 1) {
-        if (folders.has(parts[i].toLowerCase())) {
-            return `${parts[i].toLowerCase()}/${parts[i + 1].toLowerCase()}`;
+    if (parts.length === 0)
+        return undefined;
+    const bare = new Set();
+    for (const raw of sliceFolders) {
+        if (typeof raw !== 'string' || raw.length === 0)
+            continue;
+        if (isAnchoredSliceEntry(raw)) {
+            const anchored = anchoredSliceId(parts, raw);
+            if (anchored)
+                return anchored;
+            continue;
         }
+        if (!raw.includes('/') && !raw.includes('\\') && !raw.includes('*')) {
+            bare.add(raw.toLowerCase());
+        }
+    }
+    return bareSliceId(parts, bare);
+}
+/** A starred prefix with a real leading directory, not a bare name and not `*`. */
+function isAnchoredSliceEntry(entry) {
+    const segments = entry.split(/[/\\]/).filter((part) => part.length > 0);
+    if (segments.length < 2)
+        return false;
+    if (segments[0] === '*' || segments[0] === '**')
+        return false;
+    return segments.some((part) => part === '*');
+}
+function anchoredSliceId(parts, raw) {
+    const pattern = raw
+        .split(/[/\\]/)
+        .filter((part) => part.length > 0)
+        .map((part) => part.toLowerCase());
+    const offsets = anchorOffsets(parts, pattern[0] ?? '');
+    for (const offset of offsets) {
+        const id = bindAnchoredSlice(parts, pattern, offset);
+        if (id)
+            return id;
+    }
+    return undefined;
+}
+/**
+ * Walk the prefix. Literals must match. Each star binds one directory and
+ * stops before the filename; leftover stars then end the id at the last
+ * directory that did bind.
+ */
+function bindAnchoredSlice(parts, pattern, offset) {
+    const bound = [];
+    let index = offset;
+    for (let pi = 0; pi < pattern.length; pi += 1) {
+        const segment = pattern[pi];
+        if (segment === '*') {
+            if (index >= parts.length - 1) {
+                for (let rest = pi; rest < pattern.length; rest += 1) {
+                    if (pattern[rest] !== '*')
+                        return undefined;
+                }
+                break;
+            }
+            bound.push(parts[index].toLowerCase());
+            index += 1;
+            continue;
+        }
+        if (segment === '**' || index >= parts.length)
+            return undefined;
+        if (parts[index].toLowerCase() !== segment)
+            return undefined;
+        bound.push(parts[index].toLowerCase());
+        index += 1;
+    }
+    return bound.length > 0 ? bound.join('/') : undefined;
+}
+/** Bare names: leftmost folder, plus the next directory. Never the filename. */
+function bareSliceId(parts, names) {
+    if (names.size === 0)
+        return undefined;
+    for (let i = 0; i < parts.length - 1; i += 1) {
+        if (!names.has(parts[i].toLowerCase()))
+            continue;
+        if (i + 1 >= parts.length - 1)
+            continue;
+        return `${parts[i].toLowerCase()}/${parts[i + 1].toLowerCase()}`;
     }
     return undefined;
 }
@@ -279,6 +363,16 @@ function trimTrailingSlashes(value) {
 }
 /** Source folders a declared shared root may sit under without being named. */
 const SHARED_ROOT_SOURCE_PREFIXES = ['src', 'app'];
+/**
+ * Anchor at segment 0, or also at segment 1 when the path opens with `src/` or
+ * `app/` and the declaration does not itself start with that folder.
+ * Shared roots and starred slice prefixes share this offset.
+ */
+function anchorOffsets(parts, rootHead) {
+    const head = (parts[0] ?? '').toLowerCase();
+    const root = rootHead.toLowerCase();
+    return SHARED_ROOT_SOURCE_PREFIXES.includes(head) && root !== head ? [0, 1] : [0];
+}
 /** A root that would disable the wall wholesale is not a root. */
 function isBlanketRoot(raw) {
     const trimmed = trimTrailingSlashes(raw.replace(/^[./]+/, ''));
@@ -287,7 +381,7 @@ function isBlanketRoot(raw) {
 /**
  * Is `relPath` under one of the roots the rule declares shared on purpose?
  *
- * **Anchored**, unlike `sliceIdForPath`: the root must start the repo-relative
+ * **Anchored**: the root must start the repo-relative
  * path, optionally after a single conventional source folder, so `ui` covers
  * `ui/button.tsx` and `src/ui/button.tsx` but NOT `modules/a/ui/x.tsx` — an
  * unanchored root would exempt a whole tree the author never declared. Deeper
@@ -317,9 +411,7 @@ export function pathUnderSharedRoot(relPath, sharedRoots) {
         const root = normalizeSegments(raw);
         if (root.length === 0)
             continue;
-        // Anchor at segment 0, or at segment 1 when the path opens with a source
-        // folder the root does not itself name.
-        const offsets = SHARED_ROOT_SOURCE_PREFIXES.includes(parts[0]) && root[0] !== parts[0] ? [0, 1] : [0];
+        const offsets = anchorOffsets(parts, root[0] ?? '');
         for (const offset of offsets) {
             if (offset + root.length > parts.length)
                 continue;
@@ -364,7 +456,8 @@ export function crossSliceEdgeAllowed(allowedCrossSlice, fromSlice, toSlice) {
  * cross-slice edge, is the repo telling us its design, so it is no longer
  * "unclassifiable". Order: no fromPath → no slice folders → intent (no toPath):
  * shared-root allow / slice fail-closed → a side that is neither in a slice nor
- * declared shared → same slice → declared cross edge → deny.
+ * declared shared → shared root importing a slice (only when the rule denies
+ * that hop) → same slice → declared cross edge → deny.
  *
  * Intent/event names are not files. Callers pass fromPath only and must not
  * invent a toPath (that would mis-slice). A declared shared root is classified
@@ -386,6 +479,14 @@ export function peerIsolationDecision(input) {
     const toClassified = Boolean(input.toSlice) || input.toShared === true;
     if (!fromClassified || !toClassified)
         return { denied: true, reason: 'unclassifiable-path' };
+    // Shared roots are a sink. The hop is allowed unless the rule opts in.
+    // allowedCrossSlice does not excuse it: this is not a slice-to-slice edge.
+    if (input.sharedImportsSlice === 'deny' &&
+        input.fromShared === true &&
+        Boolean(input.toSlice) &&
+        !input.fromSlice) {
+        return { denied: true, reason: 'shared-imports-slice' };
+    }
     // At least one side is declared shared (and carries no slice id): the repo
     // said this code belongs to no slice, so there is no cross-slice edge here.
     if (!input.fromSlice || !input.toSlice)
@@ -416,6 +517,8 @@ export function peerIsolationDenyExplanation(reason, context) {
     switch (reason) {
         case 'cross-slice':
             return `cross-slice edge ${context.fromSlice ?? '?'} → ${context.toSlice ?? '?'}. Extract the shared code, use events/ports across slices, or declare the edge in the rule's allowedCrossSlice.`;
+        case 'shared-imports-slice':
+            return `shared root imports slice ${context.toSlice ?? '?'} (${context.fromPath ?? '?'} → ${context.toPath ?? '?'}). The wall is direct-only.`;
         case 'unclassifiable-path': {
             const unplaced = [
                 context.fromSlice ? undefined : context.fromPath,
@@ -474,6 +577,7 @@ export function findDeniedEdgeDecision(rules, from, to, options) {
                 fromShared: !fromSlice && pathUnderSharedRoot(fromPath, rule.sharedRoots),
                 toShared: !toSlice && pathUnderSharedRoot(toPath, rule.sharedRoots),
                 crossSliceAllowed: crossSliceEdgeAllowed(rule.allowedCrossSlice, fromSlice, toSlice),
+                sharedImportsSlice: rule.sharedImportsSlice,
             });
             if (decision.denied) {
                 return { rule, peerIsolationReason: decision.reason, fromSlice, toSlice };
@@ -487,6 +591,34 @@ export function findDeniedEdgeDecision(rules, from, to, options) {
     }
     return undefined;
 }
+/**
+ * Shared-root → slice edges the check still allows. Listed so a green run
+ * says the wall is direct-only. When the rule sets `sharedImportsSlice: "deny"`
+ * the same hop is a violation instead, so it is not listed twice.
+ */
+export function findSharedImportsSliceBridge(rules, from, to, options) {
+    const fromPath = options?.fromPath;
+    const toPath = options?.toPath;
+    if (!fromPath || !toPath)
+        return undefined;
+    for (const rule of rules ?? []) {
+        if (rule.from !== from || rule.to !== to)
+            continue;
+        if (rule.allowed !== false || !rule.peerIsolation)
+            continue;
+        if (rule.sharedImportsSlice === 'deny')
+            continue;
+        const folders = resolveSliceFolders(rule, from, options?.layers);
+        const fromSlice = sliceIdForPath(fromPath, folders);
+        const toSlice = sliceIdForPath(toPath, folders);
+        if (fromSlice || !toSlice)
+            continue;
+        if (!pathUnderSharedRoot(fromPath, rule.sharedRoots))
+            continue;
+        return { fromPath, toPath, toSlice };
+    }
+    return undefined;
+}
 export function isEdgeDenied(rules, from, to, options) {
     return findDeniedEdgeRule(rules, from, to, options) !== undefined;
 }

package/bin/ark.mjs

@@ -26,11 +26,13 @@ import {
   applyStartPreview,
   emitStartSetupBudgetRefuse,
   evaluateStartSetupBudgetGate,
-  formatStartPackageInstallFailure,
   planStart,
   renderStartPreview,
-  runStartPackageInstall,
 } from './lib/start-preview.mjs';
+import {
+  formatStartPackageInstallFailure,
+  runStartPackageInstall,
+} from './lib/start-install-recovery.mjs';
 import { runUpgradeCommand } from './lib/upgrade-command.mjs';
 import { detectActiveAgentHost } from './lib/skill-install.mjs';
 import { loadArkConfigContract } from './lib/config-contract.mjs';
@@ -509,6 +511,7 @@ async function start(args) {
               exitStatus: install.status,
               installCommand,
               hostOutput: `${install.stdout}\n${install.stderr}`,
+              packageVersion: cliVersion(),
             })
           );
           return install.status;
@@ -584,6 +587,7 @@ async function start(args) {
               exitStatus: installStatus,
               installCommand: `${command} ${commandArgs.join(' ')}`,
               hostOutput,
+              packageVersion: cliVersion(),
             })
           );
         }