arkgate 4.8.18 → 4.8.20

package/dist/{types-BSzRy2X1.d.ts → types-Cs-46DRu.d.ts}

@@ -1,4 +1,4 @@
-import { i as Policy, P as PolicyViolation, I as IntentName, j as IntentCreator, k as IntentRelationship, b as ArchitectureProfile, D as DomainEvent, E as EventMetadata, h as PolicyEnforcementMode, A as ArchitectureLayer, c as ArchitectureRule, d as ArkCheckConfig } from './types-D5GT5ZT8.js';
+import { i as Policy, P as PolicyViolation, I as IntentName, j as IntentCreator, k as IntentRelationship, b as ArchitectureProfile, D as DomainEvent, E as EventMetadata, h as PolicyEnforcementMode, A as ArchitectureLayer, c as ArchitectureRule, d as ArkCheckConfig } from './types-p_fCp6P-.js';
 
 /**
  * PolicyEngine

package/dist/{types-D5GT5ZT8.d.ts → types-p_fCp6P-.d.ts}

@@ -1,4 +1,4 @@
-import { a as ArkConfigRule, f as ArkConfigLayer, A as ArkConfig } from './configTypes-VD0qcubY.js';
+import { a as ArkConfigRule, f as ArkConfigLayer, A as ArkConfig } from './configTypes-VVknqcTJ.js';
 
 /**
  * Policy types for the Ark kernel.

package/docs/README.md

@@ -73,7 +73,7 @@ These are **not** the day-to-day product path. They stay in the repo for evidenc
 | Field adoption kit (scaffolding, not closed) | [field/](field/) |
 | Runtime hardening (experimental) | [production-hardening.md](production-hardening.md) |
 
-Current published: [CHANGELOG](../CHANGELOG.md) (`arkgate@4.8.18` on npm `latest`; does not close `K01`).
+Current published: [CHANGELOG](../CHANGELOG.md) (`arkgate@4.8.20` on npm `latest`; does not close `K01`).
 Prior published: [releases/4.8.11.md](releases/4.8.11.md) (`arkgate@4.8.11`).
 Prior published: [releases/4.8.10.md](releases/4.8.10.md) (`arkgate@4.8.10`).
 Prior published: [releases/4.8.9.md](releases/4.8.9.md) (`arkgate@4.8.9`).

package/docs/agent-guide.md

@@ -67,7 +67,9 @@ and trusted (Cursor: `Write` / `StrReplace` via `.cursor/hooks.json`). Codex CLI
 ChatGPT Desktop/App Server can hard-block a complete `apply_patch` through a trusted
 `.codex/hooks.json`; installed files stay unverified until a fresh covered invocation. Hosted
 tools, specialized opt-out paths, shell/direct writes, incomplete patch reconstruction, and
-OpenCode remain CI-backed or advisory. For every host, the repository-wide hard boundary is a
+OpenCode remain CI-backed or advisory. Write-gate order: host pre-hook first when
+the host has one; MCP `ark_prepare_write` is fallback if that hook is missing or
+fail-open. For every host, the repository-wide hard boundary is a
 **required GitHub status context** that runs `arkgate-check --strict-merge` (alias
 `ark-check --strict-merge`) — the CLI name is not the status context name. Soft-write or
 unverified-hook evidence alone does not mean the project is unfinished. See

package/docs/ai-gates.md

@@ -44,6 +44,10 @@ advisory-local / hard-CI split is a deliberate trade-off: local surfaces optimiz
 while a required merge status is the one boundary a repository can make every write path share.
 Prefer fail-closed honesty over fake hard guarantees on advisory hosts.
 
+**Write-gate order:** install and trust the host pre-hook first (hard when the host
+can do it). MCP `ark_prepare_write` is fallback when that path is missing or
+fail-open. OpenCode is MCP-only. Required CI is always the merge line.
+
 Everything below uses the same `ark.config.json` as `arkgate-check` / `ark-check` (CI) — one
 rules file shared by every surface. From **4.0**, optional **ArkRules** (`arkRules` map +
 `arkrules/*.json`) ride the **same** write path, doctor, and CI adapter; absence of ArkRules
@@ -350,9 +354,9 @@ alwaysApply: true
 ---
 
 Before trusting Ark MCP evidence, call `ark_identity` with `project.expectedRoot`
-set to the exact project root. Then call `ark_manifest`. Before writing TypeScript,
-prefer MCP `ark_prepare_write` / `validate_code` when available; the project
-`.cursor/hooks.json` hard gate still blocks invalid Write/StrReplace.
+set to the exact project root. Then call `ark_manifest`. The write gate is the project `.cursor/hooks.json` pre-hook when installed,
+trusted, and `failClosed`. Call MCP `ark_prepare_write` / `validate_code` only
+as fallback if that hook is missing or fail-open.
 ```
 
 Your repository backstop remains CI: `ark-check` fails its check on anything that slips

package/docs/configuration.md

@@ -114,7 +114,10 @@ Top-level fields:
   Nothing is dropped in silence: files past the budget, files over the 256KB per-file cap,
   unreadable files or directories (permissions, broken symlinks), directories past the walk depth
   limit (8), symlinks whose target resolves outside the project root, and tests naming no
-  catalogued invariant are each counted and named in the diagnostic. A symlinked test is read only
+  catalogued invariant are each counted and named in the diagnostic. Those same counts are printed
+  on a green doctor ArkRules line and on `--rules-inventory`, not only inside a failing
+  `INVARIANT_UNCOVERED` sentence. The walk-depth and per-file byte caps stay internal — they are
+  not config keys. A symlinked test is read only
   when its target is inside the root: a file that is not in this repo never proves an invariant
   covered.
 
@@ -248,11 +251,20 @@ process module-capability family must be denied.
 Rule fields:
 
 - `from`, `to`, `allowed`, `message`, `peerIsolation`, `sliceFolders`, `sharedRoots`,
-  `allowedCrossSlice`
+  `allowedCrossSlice`, `sharedImportsSlice`
 - `peerIsolation: true` + `allowed: false`: deny only when slice ids differ; same-slice allows
   when both paths classify. Applies to **any** declared `from`→`to` pair, not only self-edges.
   Missing paths, empty slice folders, or unclassifiable slices **fail closed** (deny — cannot
   prove same-slice).
+- `sliceFolders` is a bare name or a starred prefix. A bare name (`features`) stays an
+  unanchored one-segment match: `src/lib/features/projects/rfi/x.ts` with `["features"]` is
+  `features/projects`. The next segment is never a filename, so
+  `src/components/features/projects/rfi-status-pill.tsx` with `["projects"]` is not a slice.
+  A starred prefix (`lib/features/*/*`) is anchored like `sharedRoots` — it starts the
+  repo-relative path, or sits one segment in after `src/` or `app/`. Each `*` binds one
+  directory and never the filename. The slice id is those directories
+  (`lib/features/projects/rfi`). A file directly under `lib/features/projects/` stays
+  `lib/features/projects`. A path off that prefix (`src/app/api/projects/...`) is not that slice.
 
 #### Cross-layer slice walls (already in the engine)
 
@@ -306,8 +318,11 @@ is evidence:
   tree you never declared. Write a deeper or monorepo root out (`packages/web/src/ui`) or glob it
   (`packages/*/src/ui`). Matching is case-insensitive; a bare `*` or `**` is refused, because one
   character must not disable fail-closed. A path that still resolves to a slice keeps its slice —
-  `features/auth/ui/form.tsx` stays `features/auth` — so a shared root can never launder a real
-  cross-slice edge.
+  `features/auth/ui/form.tsx` stays `features/auth`. Shared roots are a sink: a slice may import
+  a shared root, and a shared root may import a slice unless the rule sets `sharedImportsSlice`
+  to `"deny"`. That hop is direct only — `allowedCrossSlice` does not excuse it. Doctor lists
+  shared-root → slice edges even when the flag is off, so a green run still says the wall is
+  direct-only.
 - `allowedCrossSlice` entries match a full slice id (`features/catalog`) or a bare slice name
   (`catalog`), and only in the direction written. The reverse edge still denies. A bare name
   matches that name under **any** slice folder, so in a repo with several slice parents
@@ -398,7 +413,7 @@ Each `arkrules/<Layer>.json` may declare:
 | Section | Purpose | Modes | What it really enforces |
 |---------|---------|--------|-------------------------|
 | `structure[]` | Closed sensor ids (e.g. `orchestration-only`, `thin-adapter`, `writes-via-aggregate`, `aggregate-private-state`, `always-valid-factory`, `domain-event-on-mutation`, `no-anemic-model`) | `advisory` (default) or `enforced` | **Heuristics of module shape** — not proof that logic was extracted to Domain. `writes-via-aggregate` is driver-import + write-token in the declaring layer (ADR 0032). Tier-2 sensors (`no-anemic-model`) stay advisory-only (cannot promote to enforced). |
-| `invariants[]` | Stable ids + description + `coverage` (`test` / `symbol`) + optional `appliesTo` globs | `advisory` or `enforced` | **Named policy + evidence** (symbol in source and/or test title/content). Does **not** execute business logic at check time and does **not** replace behavior/property tests. |
+| `invariants[]` | Stable ids + description + `coverage` (`test` / `symbol`) + optional `appliesTo` globs | `advisory` or `enforced` | **Named policy + evidence.** `coverage.symbol` means a declaration of that identifier in a non-test file (witness path `symbolEvidenceFile`); imports and test calls do not count. A test title may also name the invariant id. Does **not** execute tests or business logic and does **not** replace behavior/property tests. Doctor and `--rules-inventory` print the witness path and discard counts on green runs too. A declaration match is not “the tests pass.” |
 
 **Reporting:** diagnostics carry `evidence.arkruleId` + `evidence.arkruleSource`. Label residual
 **`[Layer]`** vs **`[ArkRules]`** in agent output. Doctor / HTML: `rulesUnderContract` (catalog +

package/docs/develop.md

@@ -35,12 +35,11 @@ ArkGate solves this by shifting the check to the exact moment of writing. By int
 ## Default integration
 
 ```bash
-npm install -D arkgate typescript
 npx arkgate start --apply
 npx --package=arkgate arkgate-check --doctor
 ```
 
-`arkgate-check` is a command in the `arkgate` 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. `arkgate-check` is a command in the `arkgate` package. After a local install, `npx arkgate-check --doctor` also works. 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.
 
 Make the import-rules check a **required** merge **status context** (GitHub/GitLab/etc.). The CLI
 command is `arkgate-check --strict-merge` / `ark-check --strict-merge` — the hard boundary is

package/docs/package-surface.md

@@ -59,7 +59,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **Effect capabilities** | Public root API: `analyzeProject(...).ir.capabilityUses`; the CLI/hook adapters add symbol-aware ambient evidence internally | Additive within IR `1.0`. Seven **closed** ids: `network`, `filesystem`, `clock`, `randomness`, `environment`, `process`, `persistence` (ADR 0009). `collectCapabilityUses` and the Domain vocabulary are internal implementation exports, **not** exports from `arkgate`; the related public low-level helper is `collectForbiddenCapabilityUses`. Direct evidence only — transitive inference never detects. The symbol-aware adapter path covers ambient globals (shadowing/type-only/globalThis-alias precision from the S05/C04 machinery) plus imports; the compiler-free IR engine carries **import-based** uses only (exact module or subpath match, never substring; textual `import type`/`export type` erasure and all-type named lists (`import { type A }`) are type-only there; mixed `{ type A, B }` stays a value import; template-literal bodies are skipped entirely (specifiers inside `${…}` are the symbol path's job); package `require(…)` counts as capability evidence only, while relative `require(…)` also emits a pure-path graph edge). **U04 walls are opt-in:** per-layer `capabilities: { deny: [...] }` or the dual-depth sugar `pure: true` (denies all seven); absence changes no verdict. `CAPABILITY_VIOLATION` is judgment-class (never mechanical-safe) with a port-injection `nextAction`; D7 dedup — evidence already owned by the layer's `forbiddenGlobals` reports only `FORBIDDEN_GLOBAL`. Y08 adds one deliberately narrow import dual: `forbiddenGlobals: ["process"]` owns exact value imports of `process` and `node:process`, but not subpaths or `child_process`; statement-level `import type` / `export type` remains erased on every path (pure-IR residual envelope: mixed `{ type A, B }`, default+named type lists, and comment-interrupted forms stay value imports; symbol path owns full precision). Atomic preflight blocks denied capabilities and that exact dual across a complete multi-file candidate (import-based on the pure path; other ambient evidence adds on the symbol-aware CLI/hook path). T01 policy-delta classifies the surface on **coverage atoms** (`ambient:<entry>` prefix-expanded, narrow `import-exact:<specifier>` duals, and `import:<capability>` for a complete wall): any lost atom is weakening (`fetch`→`XMLHttpRequest`, `Date`→`Date.now`, wall→fg all weaken; finding path `$.layers[name].capabilities`); fg → equivalent-or-stronger wall never needs an acknowledgment; unlowerable custom globals keep raw key comparison. |
 | **Ambient state (pure layers)** | `ark-check --doctor --json` → `doctor.ambientState`; optional `.ark/ambient-state-acks.json` | Additive, **advisory only and opt-in**: only layers declared `pure: true` are scanned; the MVP shape is module-scope `let`/`var`. Findings carry `file`/`line`/`name`/`kind` (sorted, capped with honest `truncated` count). Acknowledgments live in the bounded sidecar (`{ acks: [{ file, name, reason }] }`, ≤64 KB / ≤200 entries); `acknowledged` counts applied acks; malformed file suppresses nothing. When TypeScript is unavailable the sensor reports `available: false` instead of guessing. **No strict mode exists** — A5: strictness requires a completed corpus and an explicit later decision. |
 | **Parse health + analysis completeness** | `ark-check --doctor --json` → `doctor.parseHealth` + `doctor.completeness`; check JSON → `completeness`; report section `data-advisory="parseHealth"` | The resolved candidate facts contribute only `parseDiagnosticCount` per governed file (no raw diagnostics, second parser pass, or `tsc`). Z04's correctness path ignores legacy v9 caches and parses the complete candidate on every invocation; Z07 owns any future identity-keyed warm snapshot. Doctor remains diagnostic: parse health adds no architecture violation and does not change `designFitness` or `patternBets`. Verdict surfaces consume the evidence fail-closed: affected governed files mean `partial`, plan `goal.met: false`, normal JSON `valid:false`/`ok:false`, and strict merge exit `1`; the non-strict process exit remains advisory for compatibility. No usable host means `unavailable`, plan false, and CLI exit `2`. JSON reports `scannedFiles`, `affectedFiles`, `diagnosticCount`, deterministic top-12 `{ file, diagnosticCount }` entries, and honest `truncated`/`overflow`; missing/unsafe evidence never becomes a clean claim. |
-| **Physical cohesion + reshape pilot** | `ark-check --doctor --json` → `doctor.physicalCohesion` (`reshapePilot`, `reshapeDecisions`); optional `.ark/reshape-decisions.json`; report section `data-advisory="physicalCohesion"` | Additive, **advisory only** — `notAScore`; never feeds the verdict, `designFitness`, or `patternBets`. Signal is **concentration, not volume**: concept clusters per anchor directory (deterministic path/name tokenization; framework filenames like `route.ts` take the topmost meaningful path segment — ADR 0010 D2). Fixed corpus-calibrated thresholds (`maxCluster ≥ 40` OR ≥2 anchors ≥ 20, ADR 0010 D3); findings ranked and capped (top 5, honest `truncated`). Anchors under `app/`/`pages/` are `fixedByConvention` and never move (D7). `reshapePilot` is **proposed, never applied** (`neverMechanicalSafe`): one Q04-style pilot card at a time targeting the smallest convention-free anchor, with `moveSample`/`movesTotal`, `successSignal`, `killSwitch`, `doNot[]`; real moves run only through the write gate + atomic preflight via `/ark-loop`; merges are `/ark-architect` judgment cards, never a codemod (D6). **Y01 verdict memory:** bounded sidecar `{ schemaVersion?: "1", decisions: [{ concept, anchors, verdict: "accepted"|"deferred"|"rejected", reason, reviewBy? }] }` (≤64 KiB / ≤200 unique targets). Identity is concept + complete sorted anchor set, never counts/change-map evidence. Current rejected/deferred records suppress pilot pressure only; accepted keeps the existing path. Expired/malformed/stale/invalid records suppress nothing; lifecycle and decisions render in doctor/report. Explicit only — golden-pattern prose never infers a verdict. |
+| **Physical cohesion + reshape pilot** | `ark-check --doctor --json` → `doctor.physicalCohesion` (`reshapePilot`, `reshapeDecisions`); optional `.ark/reshape-decisions.json`; report section `data-advisory="physicalCohesion"` | Additive, **advisory only** — `notAScore`; never feeds the verdict, `designFitness`, or `patternBets`. Signal is **concentration, not volume**: concept clusters per anchor directory (deterministic path/name tokenization; framework filenames like `route.ts` take the topmost meaningful path segment — ADR 0010 D2). Fixed corpus-calibrated thresholds (`maxCluster ≥ 40` OR ≥2 anchors ≥ 20, ADR 0010 D3); findings ranked and capped (top 5, honest `truncated`). Anchors under `app/`/`pages/` are `fixedByConvention` and never move (D7). `reshapePilot` is **proposed, never applied** (`neverMechanicalSafe`): one Q04-style pilot card at a time targeting the smallest convention-free anchor, with `moveSample`/`movesTotal`, `successSignal`, `killSwitch`, `doNot[]`; each `to` is `concept/` under the source anchor and is kept only when layer and slice id are unchanged — if every candidate fails, `nextPilot` is null; real moves run only through the write gate + atomic preflight via `/ark-loop`; merges are `/ark-architect` judgment cards, never a codemod (D6). **Y01 verdict memory:** bounded sidecar `{ schemaVersion?: "1", decisions: [{ concept, anchors, verdict: "accepted"|"deferred"|"rejected", reason, reviewBy? }] }` (≤64 KiB / ≤200 unique targets). Identity is concept + complete sorted anchor set, never counts/change-map evidence. Current rejected/deferred records suppress pilot pressure only; accepted keeps the existing path. Expired/malformed/stale/invalid records suppress nothing; lifecycle and decisions render in doctor/report. Explicit only — golden-pattern prose never infers a verdict. |
 | **Capability walls, every adapter** | CLI scan, pure IR engine, atomic preflight, `ark-mcp --hook` / MCP gate (`capabilityWalls`), ESLint `ark/no-denied-capabilities` | The same opt-in deny set enforces across every surface: hook/MCP and CLI cover ambient + import evidence (symbol-aware); the pure engine, preflight, and ESLint cover the import dimension (documented envelope). Dual depth everywhere: plain port hint (`FIX_HINTS`/`suggestion`) + stable JSON (`ruleId`, `capability`, `fixClass: inject-port`, deterministic `nextAction`). |
 | **Hook-path budgets (maintainer)** | Repository-only evidence: `npm run bench:hook-path`; `eval/performance/hook-budgets.v1.json`; CI job "Hook-path end-to-end budgets" | Measures the COMPLETE pre-tool paths as fresh child processes (hook cold/warm, doctor cold) at 1k/10k. D5 method locked: ceilings are Linux-baseline p95 + fixed headroom, set once per cycle, never ratcheted; scenarios without a recorded baseline stay in RECORDING mode and cannot fail CI. |
 | **Governance weight** | `ark-check --doctor --json` → `doctor.contractHealth.governanceWeight` | Additive, **advisory only** — raw facts (`declaredLayers`, `populatedLayers`, `governedFiles`, `rules`, `deniedEdges`, `allowedEdges`, `filesPerLayer`, `rulesPerLayer`) plus a fixed comparative band `weight: heavy | typical | light | unknown` and its fixed `note`. Fixed deterministic thresholds: **heavy** = fewer than 25 governed files per declared layer AND (6+ layers OR 4+ well-formed rules per layer); **light** = at most 2 layers over 150+ governed files; **unknown** = no layers or no governed files; everything else is **typical** (banding uses raw ratios; the reported ratios are rounded for display). `notAScore: true` is explicit: never a composite score, ranking, or gate input; the heavy note asks to justify NEW layers/rules and never suggests deleting working ones. Human doctor prints a line only for `heavy`/`light`. |
@@ -74,7 +74,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **`arkgate/schema/project-identity`** or **`arkgate/schema/ark.project-identity.schema.json`** | MCP canonical project, contract, runtime, expectation, and binding envelope | Schema `1.0`. Initial `expectedRoot` must be the exact project root. A contained descendant can match only when `expectedProjectId` is also present and correct; id-only matching stays non-authoritative. Mismatch codes are `PROJECT_ROOT_MISMATCH`, `PROJECT_ID_MISMATCH`, and `INVALID_PROJECT_EXPECTATION`. |
 | **Package pin dual-truth (4.0)** | doctor JSON `packageVersionTruth`; upgrade JSON/human note when pin behind CLI | Additive, advisory. Surfaces after `upgrade --no-install` when managed CLI is ahead of package.json. |
 | **Managed upgrade self-service honesty (4.5 / DF05)** | `ark upgrade [--json]` → `selfService` (+ human “Self-service honesty” lines) | Additive, advisory. Answers without a maintainer: write-path activation labels per selected host (`hard`\|`advisory`\|`unavailable`) and customized content-identity preserve (`customizedPaths` / `customizedContentPreserved`). Soft hosts never hard; upgrade never invents `hardWriteActive` from disk alone. Always `notAScore: true`. Not a gate input; not part of `planDigest`. |
-| **Product honesty readiness split (4.1.1)** | doctor JSON `productHonesty` | Additive. `unfinished` / `headline` / `primaryNextAction` / `reasonIds` remain; EH adds `contractReadiness` (`ready`\|`partial`\|`not-ready`), `localWriteBoundary` (`advisory`\|`hard`\|`unverified`\|`unknown`), `architectureReasonIds`, `environmentResidualIds` / `environmentResiduals`. Soft-write hosts stay in evidence without alone forcing global **Not finished**. `notAScore: true` always. |
+| **Product honesty readiness split (4.1.1)** | doctor JSON `productHonesty` | Additive. `unfinished` / `headline` / `primaryNextAction` / `reasonIds` remain; EH adds `contractReadiness` (`ready`\|`partial`\|`not-ready`), `localWriteBoundary` (`advisory`\|`hard`\|`unverified`\|`unknown`), `architectureReasonIds`, `environmentResidualIds` / `environmentResiduals`. Soft-write hosts stay in evidence without alone forcing global **Not finished**. `notAScore: true` always. A physical-cohesion residual that reshape decisions have not suppressed adds `physical-cohesion-residual`, which clears `elegant` and `finished` and sets the headline to residual remaining; the gate verdict, `designFitness`, `designWeak`, and `patternBets` stay unchanged, and `pilotLoop` stays inactive. |
 | **Policy transition analysis (3.1.0)** | `analyzePolicyDelta(...)`; MCP `ark_policy_delta`; CLI `--policy-base` / `--policy-base-ref` / `--policy-ack`; check JSON `policyDelta` | Additive schema `1.0`. Classifications and finding ids are deterministic. Weakening/judgment requires an acknowledgement bound to both policy hashes and the exact blocking finding set. A new layer or new allow edge is `judgment-required`. On the CLI/MCP policy-ack plane, `adrPath` must name a short note under `docs/adr/` or `docs/decisions/` (`policyDelta.adrNote`). Domain hash match stays I/O-free. |
 | **Team parliament (law vs feature)** | Optional `stewards` on `ark.config.json` (GitHub handle or email); CLI `--local` / `--changed` / `--against` / `--base` / `--contract-diff` / `--contract-session` / `--persona` / `--author`; check JSON `teamParliament`; `ark status --vs`; write-gate mixed-batch deny | Additive. Law files must not mix with product source. Loosen / baseline-grow are steward-only when `stewards` is set. `--against` ratchets vs the base-ref baseline. `--changed` scans touched sources plus their import closure. `--local` (or `ARK_CHECK_LOCAL=1`) is the same cheap path and stays per `--root`; it cannot combine with `--strict-merge`. Check JSON may add `local`, `scope: "changed"`, `analysisRoot`. `stewards`, `layers[].description`, `layers[].trustBoundary`, and `layers[].owners` are excluded from policy hash. `requireLayerOwners` stays in the hash. Identity is handle or email, not git `user.name`. No org plane. |
 | **Atomic change preflight (3.1.0)** | `preflightChange(...)`; CLI `ark preflight --changes <file> --json`; MCP `ark_prepare_change` | Additive schema `1.0`. One complete governed production-source `{path,content}` / `{path,delete:true}` batch; read-only; returns operation, content/tree/policy/compiler fingerprints and stable graph findings. MCP availability alone is advisory. |

package/docs/use.md

@@ -24,14 +24,13 @@ For **anyone** shipping TypeScript with an AI coding agent.
 ## In one minute
 
 ```bash
-npm install -D arkgate typescript
 npx arkgate start                 # preview what will change
 npx arkgate start --apply         # install compact config + host router + CI; merge write-path gates into existing AGENTS.md / .mcp.json
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.8.18",
+  "version": "4.8.20",
   "description": "When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -205,14 +205,14 @@
     "@stryker-mutator/core": "^9.6.1",
     "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/node": "^20.14.0",
-    "@vitest/coverage-v8": "^3.2.6",
+    "@vitest/coverage-v8": "^4.1.11",
     "esbuild": "0.28.1",
     "fast-check": "^4.9.0",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.2",
     "tsup": "^8.1.0",
     "typescript": "5.9.3",
-    "vitest": "^3.2.6"
+    "vitest": "^4.1.11"
   },
   "engines": {
     "node": ">=18"

package/schemas/ark.config.schema.json

@@ -828,6 +828,12 @@
               }
             }
           }
+        },
+        "sharedImportsSlice": {
+          "type": "string",
+          "enum": [
+            "deny"
+          ]
         }
       }
     },

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "4.8.18",
+  "version": "4.8.20",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.8.18",
+      "version": "4.8.20",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/agent-skills/README.md

@@ -9,7 +9,7 @@ closed `/ark-*` catalog shipped as flat templates for Ark install.
 **Closed catalog** (`ARK_SKILL_NAMES`) — first-class doors plus one-release
 redirect stubs. Add a name only with a live ROADMAP item.
 
-Package version when last generated context: **arkgate@4.8.18**
+Package version when last generated context: **arkgate@4.8.20**
 Schema: agent-skills package contract `1.0`
 
 ## Skills (closed catalog)

package/templates/agent-skills/ark-adopt/SKILL.md

@@ -63,6 +63,11 @@ has honest houses. Skills never enforce — CLI / hooks / CI do.
   `coverage.coverageRoots` to the folder the test runner uses. Fail-closed
   until that path exists. `coverage.testGlobs` alone is not enough. Silent
   when no invariant is enforced. No new skill.
+- `coverage.symbol` means a declaration of that identifier in a non-test file.
+  Doctor and `--rules-inventory` print `symbolEvidenceFile` and the discard
+  counts even when uncovered is 0. Read that path. Imports and calls in tests
+  do not count. That declaration text is not “the tests pass” — ArkGate never
+  runs tests. No new config key.
 - CLI-first: if `arkgate-check` already resolved the root, do not wait on MCP.
 - Do not add `arkRun` or `arkOrder` unless the user wants that extra. When they do, write
   **advisory** extra in this turn (`arkRun` schema `1.2+`; `arkOrder` schema `1.3+`).
@@ -353,8 +358,17 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    The denial names its reason. `unclassifiable path` in bulk means shared code lives outside
    the slice folders — declare those roots (`sharedRoots`) on the rule instead of treating
    thousands of shared files as violations; `cross-slice edge a → b` is the real one, and a
-   deliberate directed edge goes in `allowedCrossSlice`. Promoting the shared slice to its own
+   deliberate directed edge goes in `allowedCrossSlice`. Shared roots are a sink: a slice may
+   import them, and they may import a slice. Doctor lists that shared-root → slice hop even
+   when the check stays green, so the wall is direct-only. `sharedImportsSlice: "deny"` closes
+   that one hop; it does not finish the wall. Promoting the shared slice to its own
    layer is still the preferred fix.
+   `sliceFolders`: a bare name stays an unanchored one-segment match (`features` on
+   `src/lib/features/projects/rfi/x.ts` is `features/projects`); a filename is never the
+   child segment. A starred prefix (`lib/features/*/*`) is anchored like `sharedRoots`
+   (offset 0 or 1) and the slice id is the directories the stars bind
+   (`lib/features/projects/rfi`). Before trusting green, add one deliberate
+   feature-to-feature import and expect `cross-slice`.
    If one edge dominates residual debt: **STOP — do not continue this skill as complete.** **STOP — concentrated edge:** rewrite `ark.config.json` **in this turn** with source evidence (do not freeze a wrong config or grind N freezes).
    Empty Domain/Persistence + I/O under Application → false-green.
    **STOP — do not continue this skill as complete.** **STOP — false-green:** fix the config **in this turn** before claiming ENFORCE. Do not claim goal.met / ENFORCE from type-only cleanup while doctor reports `contract-false-green-io-under-application`.

package/templates/agent-skills/ark-autopilot/SKILL.md

@@ -110,6 +110,8 @@ decision-grade explore pass **and** without opening violating files.
    layout — no pilot”; never reconstruct that dead card from `findings`. When the user accepts,
    defers, or rejects a live card, persist its exact `decisionTarget` with a non-empty reason and
    optional `reviewBy` in `.ark/reshape-decisions.json`; never infer a verdict from golden prose.
+   A cohesion residual starts one reshape judgment card, not the pattern-bet apply loop.
+   `pilotLoop` stays inactive (`not-design-weak`) unless the tree is design-weak.
 
 
 

package/templates/agent-skills/ark-coverage/SKILL.md

@@ -96,7 +96,7 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
 4. Editing `arkrules/*` or promoting modes is **`/ark-adopt`**; fixing code under a structure sensor is **`/ark-autopilot`** (judgment, never invent mechanical-safe).
 5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` / `INVARIANT_CATALOG_EMPTY` with `evidence.arkruleId`.
-5b. Invariant coverage is a **text match, never an execution**: a file walk plus the invariant id in a `describe`/`it` title. Never report `INVARIANT_UNCOVERED: 0` as “the tests pass” or “the tests run” — ArkGate does not run tests and reads no runner config. When the project declares `coverage.coverageRoots`, a covering test found outside them raises the advisory `INVARIANT_COVERAGE_OUTSIDE_ROOTS`; without that declaration ArkGate makes no claim about where tests run. Adopted + catalogued invariants without `coverage.testGlobs` or `coverage.coverageRoots` fails closed (`INVARIANT_TESTS_PATH_MISSING`) — write the path (`/ark-adopt`). When any invariant is enforced, missing `coverage.coverageRoots` fails closed (`INVARIANT_COVERAGE_ROOTS_MISSING`) — write the runner roots (`/ark-adopt`). `testGlobs` alone is not enough.
+5b. Invariant coverage is a **text match, never an execution**: a file walk plus the invariant id in a `describe`/`it` title. `coverage.symbol` means a declaration of that identifier in a non-test file (`symbolEvidenceFile`); imports and test calls do not count. Doctor and `--rules-inventory` print that witness path and the scan discard counts on a green run too. Never report `INVARIANT_UNCOVERED: 0`, a witness path, or a discard line as “the tests pass” or “the tests run” — ArkGate does not run tests and reads no runner config. Declaration text is not “the tests pass.” When the project declares `coverage.coverageRoots`, a covering test found outside them raises the advisory `INVARIANT_COVERAGE_OUTSIDE_ROOTS`; without that declaration ArkGate makes no claim about where tests run. Adopted + catalogued invariants without `coverage.testGlobs` or `coverage.coverageRoots` fails closed (`INVARIANT_TESTS_PATH_MISSING`) — write the path (`/ark-adopt`). When any invariant is enforced, missing `coverage.coverageRoots` fails closed (`INVARIANT_COVERAGE_ROOTS_MISSING`) — write the runner roots (`/ark-adopt`). `testGlobs` alone is not enough.
 6. Extras silent when off. Doctor `arkRun` / `arkOrder` is `notAScore`. Do not force extras. Wire one kernel candidate via `/ark-runtime`; one order-plane candidate via `/ark-order`. Do not invent `/ark-run`.
 
 

package/templates/agent-skills/ark-explain/SKILL.md

@@ -188,7 +188,7 @@ else is judgment/deferred and must not be auto-applied.
 **Type-edge honesty:** type-only denied edges are **placement debt** (`typeOnly` +
 `failsStrict: false`) — prefer SharedTypes / owning layer; they do not fail merge like value
 edges. Doctor `productHonesty` and `violations.typeEdgePolicy` must not be sold as “all done”
-when residual signals remain.
+when residual signals remain (`physical-cohesion-residual` included).
 
 ## Spoken / written explanation
 

package/templates/agent-skills/ark-explore/SKILL.md

@@ -53,6 +53,11 @@ one bounded decision needs 2–3 enforceable options.
   `coverage.coverageRoots` on the folder the test runner uses. Fail-closed.
   `testGlobs` alone is not enough. Silent when no invariant is enforced.
   Handoff `/ark-adopt` to write the roots. No new skill.
+- When an invariant declares `coverage.symbol`, read the witness path
+  (`symbolEvidenceFile`) and the discard line on doctor and `--rules-inventory`,
+  including when the run is green. A declaration in a non-test file is not
+  “the tests pass” — ArkGate never runs tests. Depth and byte caps stay
+  internal; the counts are what you read.
 - A doctor green / Healthy line must name a file, config key, or test.
   Uncited green is a lie — treat it as unfinished. No `/ark-cite`.
 - Distinguish **missing** skills vs **stale** catalog. Installed ≠ stale.
@@ -345,12 +350,19 @@ targets as explicit adopter decisions, not residual to re-fight. Keep their mirr
 map. When the user accepts, defers, or rejects a live `reshapePilot.nextPilot`, record the card's
 exact `decisionTarget` with a reason (and optional `reviewBy`) in
 `.ark/reshape-decisions.json`. Never infer or suppress from free-form golden-pattern prose.
+A proposed `to` stays under the source anchor (`concept/`) and is kept only when that path
+stays in the same layer and the same slice id. If no governed destination keeps both,
+`nextPilot` is null — do not invent a folder outside the contract. Success is a smaller
+cluster with the layer and slice id unchanged and the card still proposed; a green gate is
+not success. A cohesion residual (`physical-cohesion-residual`) starts that one reshape
+judgment card. It does not start the pattern-bet apply loop — `pilotLoop` stays inactive
+while design-weak is false.
 
 ### C. Coupling & debt (measure, don’t guess)
 Prefer evidence over aesthetics:
 - **Fan-in / importers** of hot modules (who imports the suspect file?).
 - **Export surface** (how many public symbols does the orchestration module re-export?).
-- Import cycles, cross-feature leaks (`peerIsolation` candidates).
+- Import cycles, cross-feature leaks (`peerIsolation` candidates). A shared root that imports a slice is a direct-only bridge; doctor lists it. `sharedImportsSlice: "deny"` closes that one hop. It does not finish the wall.
 - Business rules in UI/hooks (`can*`, `calculate*`, policy constants) → Domain / intents.
 - Dead or aspirational globs; layers with files but no rules; **starter/preset rules weaker than sibling archetypes** (soft green).
 - LOC is a **hint** only — pair it with fan-in or export count before calling something a god module.

package/templates/agent-skills/ark-place/SKILL.md

@@ -21,6 +21,8 @@ right house. Skills never enforce — CLI / hooks / CI do.
 ## Checklist
 
 - `filePath` is known before the call. Description alone is not a path.
+- Host write gate: prefer the installed pre-hook. MCP `ark_prepare_write` is
+  fallback when that hook is missing or fail-open. Skills never enforce.
 - Golden pattern is load-bearing when present. Adopt generates it.
 - An included file that matches no layer is not a pass. The write gate denies it
   (`CONFIG_UNCLASSIFIED_FILES`). Place it in a layer folder, or send include/layer

package/templates/agent-skills/ark-upgrade/SKILL.md

@@ -259,9 +259,11 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
    If already current (`ALREADY_CURRENT`), retain the read-only preview and still read `whatsNew`
    + `skillDrift`.
 
-   For pnpm repositories with `minimumReleaseAge`, use the repository's existing
-   trusted first-party exception mechanism when the new release is still cooling
-   off, and prove `pnpm install --frozen-lockfile` succeeds.
+   For pnpm repositories with `minimumReleaseAge`, put the exception on
+   `minimumReleaseAgeExclude` in pnpm config or `pnpm-workspace.yaml` (a CLI
+   flag is not enough) when the new release is still cooling off, or keep using
+   `npx --package=arkgate@<pin>` until the package is mature. Prove
+   `pnpm install --frozen-lockfile` succeeds after a local add.
 
 4. **Apply only the reviewed candidate.** When there are no blocked assets, run
    the preview's **exact** `nextCommand` as emitted (JSON field / human “Apply the

package/templates/hooks/opencode-ark-write-gate.mjs

@@ -8,8 +8,8 @@
  *
  * Honesty: OpenCode plugin hooks are **not** a complete hard write boundary
  * (subagent and alternate tool paths may bypass). Never treat this plugin as
- * Claude/Grok/Antigravity PreToolUse hard-write. Prefer MCP `ark_prepare_write`
- * + required merge status.
+ * Claude/Grok/Antigravity PreToolUse hard-write. This host has no hard pre-hook,
+ * so MCP `ark_prepare_write` is the local write fallback + required merge status.
  *
  * This file is a gallery template shipped with arkgate — not auto-installed.
  */

package/templates/skills/ark-adopt.md

@@ -63,6 +63,11 @@ has honest houses. Skills never enforce — CLI / hooks / CI do.
   `coverage.coverageRoots` to the folder the test runner uses. Fail-closed
   until that path exists. `coverage.testGlobs` alone is not enough. Silent
   when no invariant is enforced. No new skill.
+- `coverage.symbol` means a declaration of that identifier in a non-test file.
+  Doctor and `--rules-inventory` print `symbolEvidenceFile` and the discard
+  counts even when uncovered is 0. Read that path. Imports and calls in tests
+  do not count. That declaration text is not “the tests pass” — ArkGate never
+  runs tests. No new config key.
 - CLI-first: if `arkgate-check` already resolved the root, do not wait on MCP.
 - Do not add `arkRun` or `arkOrder` unless the user wants that extra. When they do, write
   **advisory** extra in this turn (`arkRun` schema `1.2+`; `arkOrder` schema `1.3+`).
@@ -353,8 +358,17 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    The denial names its reason. `unclassifiable path` in bulk means shared code lives outside
    the slice folders — declare those roots (`sharedRoots`) on the rule instead of treating
    thousands of shared files as violations; `cross-slice edge a → b` is the real one, and a
-   deliberate directed edge goes in `allowedCrossSlice`. Promoting the shared slice to its own
+   deliberate directed edge goes in `allowedCrossSlice`. Shared roots are a sink: a slice may
+   import them, and they may import a slice. Doctor lists that shared-root → slice hop even
+   when the check stays green, so the wall is direct-only. `sharedImportsSlice: "deny"` closes
+   that one hop; it does not finish the wall. Promoting the shared slice to its own
    layer is still the preferred fix.
+   `sliceFolders`: a bare name stays an unanchored one-segment match (`features` on
+   `src/lib/features/projects/rfi/x.ts` is `features/projects`); a filename is never the
+   child segment. A starred prefix (`lib/features/*/*`) is anchored like `sharedRoots`
+   (offset 0 or 1) and the slice id is the directories the stars bind
+   (`lib/features/projects/rfi`). Before trusting green, add one deliberate
+   feature-to-feature import and expect `cross-slice`.
    If one edge dominates residual debt: **STOP — do not continue this skill as complete.** **STOP — concentrated edge:** rewrite `ark.config.json` **in this turn** with source evidence (do not freeze a wrong config or grind N freezes).
    Empty Domain/Persistence + I/O under Application → false-green.
    **STOP — do not continue this skill as complete.** **STOP — false-green:** fix the config **in this turn** before claiming ENFORCE. Do not claim goal.met / ENFORCE from type-only cleanup while doctor reports `contract-false-green-io-under-application`.

package/templates/skills/ark-autopilot.md

@@ -110,6 +110,8 @@ decision-grade explore pass **and** without opening violating files.
    layout — no pilot”; never reconstruct that dead card from `findings`. When the user accepts,
    defers, or rejects a live card, persist its exact `decisionTarget` with a non-empty reason and
    optional `reviewBy` in `.ark/reshape-decisions.json`; never infer a verdict from golden prose.
+   A cohesion residual starts one reshape judgment card, not the pattern-bet apply loop.
+   `pilotLoop` stays inactive (`not-design-weak`) unless the tree is design-weak.
 
 
 

package/templates/skills/ark-coverage.md

@@ -96,7 +96,7 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
 4. Editing `arkrules/*` or promoting modes is **`/ark-adopt`**; fixing code under a structure sensor is **`/ark-autopilot`** (judgment, never invent mechanical-safe).
 5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` / `INVARIANT_CATALOG_EMPTY` with `evidence.arkruleId`.
-5b. Invariant coverage is a **text match, never an execution**: a file walk plus the invariant id in a `describe`/`it` title. Never report `INVARIANT_UNCOVERED: 0` as “the tests pass” or “the tests run” — ArkGate does not run tests and reads no runner config. When the project declares `coverage.coverageRoots`, a covering test found outside them raises the advisory `INVARIANT_COVERAGE_OUTSIDE_ROOTS`; without that declaration ArkGate makes no claim about where tests run. Adopted + catalogued invariants without `coverage.testGlobs` or `coverage.coverageRoots` fails closed (`INVARIANT_TESTS_PATH_MISSING`) — write the path (`/ark-adopt`). When any invariant is enforced, missing `coverage.coverageRoots` fails closed (`INVARIANT_COVERAGE_ROOTS_MISSING`) — write the runner roots (`/ark-adopt`). `testGlobs` alone is not enough.
+5b. Invariant coverage is a **text match, never an execution**: a file walk plus the invariant id in a `describe`/`it` title. `coverage.symbol` means a declaration of that identifier in a non-test file (`symbolEvidenceFile`); imports and test calls do not count. Doctor and `--rules-inventory` print that witness path and the scan discard counts on a green run too. Never report `INVARIANT_UNCOVERED: 0`, a witness path, or a discard line as “the tests pass” or “the tests run” — ArkGate does not run tests and reads no runner config. Declaration text is not “the tests pass.” When the project declares `coverage.coverageRoots`, a covering test found outside them raises the advisory `INVARIANT_COVERAGE_OUTSIDE_ROOTS`; without that declaration ArkGate makes no claim about where tests run. Adopted + catalogued invariants without `coverage.testGlobs` or `coverage.coverageRoots` fails closed (`INVARIANT_TESTS_PATH_MISSING`) — write the path (`/ark-adopt`). When any invariant is enforced, missing `coverage.coverageRoots` fails closed (`INVARIANT_COVERAGE_ROOTS_MISSING`) — write the runner roots (`/ark-adopt`). `testGlobs` alone is not enough.
 6. Extras silent when off. Doctor `arkRun` / `arkOrder` is `notAScore`. Do not force extras. Wire one kernel candidate via `/ark-runtime`; one order-plane candidate via `/ark-order`. Do not invent `/ark-run`.
 
 

package/templates/skills/ark-explain.md

@@ -188,7 +188,7 @@ else is judgment/deferred and must not be auto-applied.
 **Type-edge honesty:** type-only denied edges are **placement debt** (`typeOnly` +
 `failsStrict: false`) — prefer SharedTypes / owning layer; they do not fail merge like value
 edges. Doctor `productHonesty` and `violations.typeEdgePolicy` must not be sold as “all done”
-when residual signals remain.
+when residual signals remain (`physical-cohesion-residual` included).
 
 ## Spoken / written explanation
 

package/templates/skills/ark-explore.md

@@ -53,6 +53,11 @@ one bounded decision needs 2–3 enforceable options.
   `coverage.coverageRoots` on the folder the test runner uses. Fail-closed.
   `testGlobs` alone is not enough. Silent when no invariant is enforced.
   Handoff `/ark-adopt` to write the roots. No new skill.
+- When an invariant declares `coverage.symbol`, read the witness path
+  (`symbolEvidenceFile`) and the discard line on doctor and `--rules-inventory`,
+  including when the run is green. A declaration in a non-test file is not
+  “the tests pass” — ArkGate never runs tests. Depth and byte caps stay
+  internal; the counts are what you read.
 - A doctor green / Healthy line must name a file, config key, or test.
   Uncited green is a lie — treat it as unfinished. No `/ark-cite`.
 - Distinguish **missing** skills vs **stale** catalog. Installed ≠ stale.
@@ -345,12 +350,19 @@ targets as explicit adopter decisions, not residual to re-fight. Keep their mirr
 map. When the user accepts, defers, or rejects a live `reshapePilot.nextPilot`, record the card's
 exact `decisionTarget` with a reason (and optional `reviewBy`) in
 `.ark/reshape-decisions.json`. Never infer or suppress from free-form golden-pattern prose.
+A proposed `to` stays under the source anchor (`concept/`) and is kept only when that path
+stays in the same layer and the same slice id. If no governed destination keeps both,
+`nextPilot` is null — do not invent a folder outside the contract. Success is a smaller
+cluster with the layer and slice id unchanged and the card still proposed; a green gate is
+not success. A cohesion residual (`physical-cohesion-residual`) starts that one reshape
+judgment card. It does not start the pattern-bet apply loop — `pilotLoop` stays inactive
+while design-weak is false.
 
 ### C. Coupling & debt (measure, don’t guess)
 Prefer evidence over aesthetics:
 - **Fan-in / importers** of hot modules (who imports the suspect file?).
 - **Export surface** (how many public symbols does the orchestration module re-export?).
-- Import cycles, cross-feature leaks (`peerIsolation` candidates).
+- Import cycles, cross-feature leaks (`peerIsolation` candidates). A shared root that imports a slice is a direct-only bridge; doctor lists it. `sharedImportsSlice: "deny"` closes that one hop. It does not finish the wall.
 - Business rules in UI/hooks (`can*`, `calculate*`, policy constants) → Domain / intents.
 - Dead or aspirational globs; layers with files but no rules; **starter/preset rules weaker than sibling archetypes** (soft green).
 - LOC is a **hint** only — pair it with fan-in or export count before calling something a god module.

package/templates/skills/ark-place.md

@@ -21,6 +21,8 @@ right house. Skills never enforce — CLI / hooks / CI do.
 ## Checklist
 
 - `filePath` is known before the call. Description alone is not a path.
+- Host write gate: prefer the installed pre-hook. MCP `ark_prepare_write` is
+  fallback when that hook is missing or fail-open. Skills never enforce.
 - Golden pattern is load-bearing when present. Adopt generates it.
 - An included file that matches no layer is not a pass. The write gate denies it
   (`CONFIG_UNCLASSIFIED_FILES`). Place it in a layer folder, or send include/layer

package/templates/skills/ark-upgrade.md

@@ -259,9 +259,11 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
    If already current (`ALREADY_CURRENT`), retain the read-only preview and still read `whatsNew`
    + `skillDrift`.
 
-   For pnpm repositories with `minimumReleaseAge`, use the repository's existing
-   trusted first-party exception mechanism when the new release is still cooling
-   off, and prove `pnpm install --frozen-lockfile` succeeds.
+   For pnpm repositories with `minimumReleaseAge`, put the exception on
+   `minimumReleaseAgeExclude` in pnpm config or `pnpm-workspace.yaml` (a CLI
+   flag is not enough) when the new release is still cooling off, or keep using
+   `npx --package=arkgate@<pin>` until the package is mature. Prove
+   `pnpm install --frozen-lockfile` succeeds after a local add.
 
 4. **Apply only the reviewed candidate.** When there are no blocked assets, run
    the preview's **exact** `nextCommand` as emitted (JSON field / human “Apply the