arkgate 4.8.18 → 4.8.20

package/CHANGELOG.md

@@ -96,6 +96,159 @@ 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
+ships that landed after 4.8.18 published: pre-hook write gate first
+([#280](https://github.com/pedroknigge/arkgate/pull/280)), honest
+workspace evidence + playground exclude
+([#286](https://github.com/pedroknigge/arkgate/pull/286)), skill stamp
+refresh ([#285](https://github.com/pedroknigge/arkgate/pull/285)),
+honest start docs and install-fail next step
+([#287](https://github.com/pedroknigge/arkgate/pull/287)), and honest
+recommend label when `uiHeavy` is true
+([#289](https://github.com/pedroknigge/arkgate/pull/289)).
+**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.19**).
+
+### Changed
+- Write-gate order: install and trust the host pre-hook first. MCP
+  `ark_prepare_write` is fallback when that path is missing or fail-open.
+  Compact Cursor now requires the fail-closed hook (MCP alone is not
+  enough). Doctor / start / host matrix name the fallback
+  ([#280](https://github.com/pedroknigge/arkgate/pull/280)).
+
+### Fixed
+- Stranger-path `--recommend` treats `pnpm-workspace.yaml` (even without
+  `package.json#workspaces`) as workspace evidence, and no longer says
+  "not a workspace monorepo" on a workspace tree. Start / recommend skip
+  playground, fixture, and scaffold trees the same way the check walk
+  does ([#286](https://github.com/pedroknigge/arkgate/pull/286)).
+- Managed upgrade refreshes a skill's `arkVersion` / `arkgate@X.Y.Z`
+  description stamp when the body is unchanged (`state: current`).
+  Frozen redirect stubs no longer keep a stale picker version after a
+  pin bump. Reuses `planSkillInstall` `stamp-refresh`;
+  `summary.metadataRefresh` counts those writes
+  ([#285](https://github.com/pedroknigge/arkgate/pull/285) /
+  [#284](https://github.com/pedroknigge/arkgate/issues/284)).
+- Stranger start path no longer leads with `npm install -D arkgate`
+  (hard-fail on `workspace:*`). Docs lead with `npx arkgate start`;
+  `start --apply` already pins with `pnpm add -w` / `yarn add -W`.
+  pnpm `minimumReleaseAge` recovery is a one-liner. Doctor after a
+  failed install leads with resolve the package, not "make CI required"
+  ([#287](https://github.com/pedroknigge/arkgate/pull/287) /
+  [#268](https://github.com/pedroknigge/arkgate/issues/268)).
+- `start` / `--recommend` no longer labels a UI monorepo as "API server
+  without UI in this repository" when `uiHeavy` is true. The one-minute
+  label becomes "API-heavy monorepo with UI packages". Default monorepo
+  start parks `web/**` / `web/src/**` on PresentationAdapters
+  ([#289](https://github.com/pedroknigge/arkgate/pull/289) /
+  [#288](https://github.com/pedroknigge/arkgate/issues/288)).
+
 ## 4.8.18 — 2026-09-18
 
 **Patch** over **4.8.17**. Daily accumulate (2026-09-18 ART) of the six

package/README.md

@@ -39,7 +39,7 @@ Works with Cursor, Claude, Codex, and Grok.
 
 </div>
 
-> **ArkGate 4.8.18** 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.18](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)
 
 ---
 
@@ -66,14 +66,13 @@ Full map: **[docs/README.md](docs/README.md)**
 ## Start in one minute
 
 ```bash
-npm install -D arkgate typescript
 npx arkgate start                 # preview files + commands
 npx arkgate start --apply         # compact config + host router + CI plan
 npx --package=arkgate arkgate-check --doctor        # status — one next step
 npx --package=arkgate arkgate-check --doctor --all  # full details
 ```
 
-`arkgate-check` is a command in the `arkgate` package, not its own npm package. After a local install, `npx arkgate-check --doctor` also works.
+`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
@@ -204,7 +203,7 @@ Codex hard write covers only a complete local `apply_patch`; Cursor covers only
 installed + trusted, while shell/direct
 filesystem writes, hosted or specialized opt-out paths, and human edits still rely on CI.
 
-This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run `arkgate-check --doctor` (or `ark-check --doctor`) for the evidence actually detected in the current repository.
+This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. **Write-gate order:** install and trust the host pre-hook first. MCP prepare is fallback when that path is missing or fail-open. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run `arkgate-check --doctor` (or `ark-check --doctor`) for the evidence actually detected in the current repository.
 <!-- arkgate-host-support:end -->
 
 #### Why required CI is the hard line
@@ -347,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.18 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-mcp-runtime.mjs

@@ -2037,8 +2037,8 @@ export async function runArkMcp({ hookInput } = {}) {
         'When the matched layer has layers[].description, the JSON includes description; the field is omitted when absent. ' +
         'When the matched layer has layers[].trustBoundary (public|auth|admin|internal), the JSON includes trustBoundary; omitted when absent. ' +
         'When the matched layer has layers[].owners, the JSON includes owners; omitted when absent. ' +
-        'Call BEFORE writing a new file. ' +
-        'Prefer ark_prepare_write when you already have the source snippet (place+validate+autoPatch in one call).',
+        'Call BEFORE writing a new file to learn the layer. ' +
+        'Prefer ark_prepare_write only as fallback when the host has no hard pre-hook (or that hook is missing / fail-open) and you already have the source snippet.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -2061,7 +2061,7 @@ export async function runArkMcp({ hookInput } = {}) {
         'constrain (layer, mayImport, mustNotImport, forbiddenGlobals) + validate source + optional ' +
         'mechanical-safe autoPatch + judgmentBrief when judgment is needed + contentHash for host commit. ' +
         'Also returns the versioned new/worsened designDelta for the proposed full file. ' +
-        'Composes ark_place + write-gate — call BEFORE Write/Edit when you have the snippet. ' +
+        'Composes ark_place + write-gate. Fallback when the host has no trusted hard pre-hook (or that hook is fail-open). When a hard hook is installed, the host already gates the write; this tool stays available but is not the primary gate. ' +
         'When the matched layer has layers[].description, the JSON includes description; the field is omitted when absent. ' +
         'When the matched layer has layers[].trustBoundary (public|auth|admin|internal), the JSON includes trustBoundary; omitted when absent. ' +
         'When the matched layer has layers[].owners, the JSON includes owners; omitted when absent. ' +