arkgate 4.8.20 → 4.8.22

package/CHANGELOG.md

@@ -96,6 +96,165 @@ 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.22 — 2026-09-27
+
+**Patch** over **4.8.21**. Daily accumulate (2026-09-27 ART) of the ships
+that landed after 4.8.21 published: `coverage.symbol` recognizes
+`export const X: Type =` (including `=>` inside a function type) and a
+cross-file comment is reported as `no declaration matched`
+([#324](https://github.com/pedroknigge/arkgate/pull/324) /
+[#322](https://github.com/pedroknigge/arkgate/issues/322)), test titles that
+contain the other quote character count as coverage
+([#324](https://github.com/pedroknigge/arkgate/pull/324) /
+[#323](https://github.com/pedroknigge/arkgate/issues/323)), and a packed
+journey matrix in CI
+([#324](https://github.com/pedroknigge/arkgate/pull/324)).
+**Write. Check. Ship.** **No required config migration.** No
+`schemaVersion` bump. No new behavior change: both fixes only accept
+coverage that 4.8.21 wrongly rejected. Does not close `K01` / `Z09`. This
+mother `ark.config.json` still does **not** turn `arkOrder` on.
+
+**Status: released** (tag `v4.8.22`). This file does not assert registry
+state; run `npm view arkgate@4.8.22 version` to confirm the package is
+available (#314).
+
+### Fixed
+- Test-title coverage accepts a `describe`/`it` title that contains the other
+  quote character, such as `it("… <input type='file'> …")`
+  ([#324](https://github.com/pedroknigge/arkgate/pull/324) /
+  [#323](https://github.com/pedroknigge/arkgate/issues/323)).
+- Const-declaration coverage accepts a type annotation between the name and
+  `=`, including `=>` inside a function type (`export const X: ReadonlyArray<…> =`,
+  `export const f: (a: A) => B =`). When that declaration does not match and the
+  only comment is in a different file, the message is `no declaration matched`,
+  not "appears only in a comment"
+  ([#324](https://github.com/pedroknigge/arkgate/pull/324) /
+  [#322](https://github.com/pedroknigge/arkgate/issues/322)).
+
+### Known limitation
+- `coverage.symbol` still does not recognize a declaration exported through
+  an export list (`const X = …` plus `export { X }`). Declare it with
+  `export const X` (or point `coverage.symbol` at a function, class, type,
+  interface, or enum declaration) until that form is supported.
+
+### Changed
+- Internal: packed journey matrix (`journey(fixture, steps)`) installs the
+  npm tarball into a vendored realistic fixture (`ledgerline`) and compares
+  a JSON subset to a committed golden. CI runs one job per fixture. Unit tests and coverage
+  floors are unchanged. No product behavior change
+  ([#324](https://github.com/pedroknigge/arkgate/pull/324)).
+
+## 4.8.21 — 2026-09-26
+
+**Patch** over **4.8.20**. Daily accumulate (2026-09-26 ART) of the ships
+that landed after 4.8.20 published: a bare invariant-id mention is not
+coverage and `coverage.symbol` accepts `type` / `interface` / `enum` again
+([#319](https://github.com/pedroknigge/arkgate/pull/319) /
+[#310](https://github.com/pedroknigge/arkgate/issues/310),
+[#307](https://github.com/pedroknigge/arkgate/issues/307)), one explained
+`arkgate upgrade --apply` outcome with exit `3` for applied but red
+([#320](https://github.com/pedroknigge/arkgate/pull/320) /
+[#311](https://github.com/pedroknigge/arkgate/issues/311),
+[#312](https://github.com/pedroknigge/arkgate/issues/312)), optional
+`sliceIdentity: "stars"`
+([#318](https://github.com/pedroknigge/arkgate/pull/318) /
+[#308](https://github.com/pedroknigge/arkgate/issues/308)), grouped
+`SHARED_IMPORTS_SLICE` human output
+([#316](https://github.com/pedroknigge/arkgate/pull/316) /
+[#313](https://github.com/pedroknigge/arkgate/issues/313)), pilot loop sees
+reshape pilots
+([#317](https://github.com/pedroknigge/arkgate/pull/317) /
+[#309](https://github.com/pedroknigge/arkgate/issues/309)), README
+first-contact rewrite
+([#306](https://github.com/pedroknigge/arkgate/pull/306)), and docs fixes
+([#315](https://github.com/pedroknigge/arkgate/pull/315)).
+**Write. Check. Ship.** **Behavior change:** some repos that are green
+today can turn red, and scripts that compare `arkgate upgrade --apply`
+against exit `1` must compare non-zero. See the two notes under Changed.
+No `schemaVersion` bump. Does not close `K01` / `Z09`. This mother
+`ark.config.json` still does **not** turn `arkOrder` on.
+
+**Status: released** (tag `v4.8.21`). This file does not assert registry
+state; run `npm view arkgate@4.8.21 version` to confirm the package is
+available (#314).
+
+### Changed
+- **Behavior change.** A comment, a string, a test body, or an import that merely
+  mentions an invariant id no longer counts as coverage. Only a `describe` /
+  `it` / `test` / `context` title does. Repos that were green because a comment
+  or a string contained the id will turn red. One-line fix: move the id into
+  the `it()` title.
+  ([#319](https://github.com/pedroknigge/arkgate/pull/319) /
+  [#310](https://github.com/pedroknigge/arkgate/issues/310))
+- **Behavior change for scripts.** `arkgate upgrade --apply` reports one
+  outcome. Exit `0` means applied and the architecture check is green (or
+  there was nothing to apply). Exit `3` means applied but red, so scripts
+  that compare against exit `1` must compare non-zero. Exit `2` means
+  blocked until you consent. Exit `1` means error, including a stale `--plan-digest` (that path was exit `2`). A stale CLI
+  outside the project still refuses with exit `2` before any plan. JSON stays
+  additive: `outcome`, `postUpgrade.verdict`, `postUpgrade.failing`
+  (`ruleId`, `count`, `sample`), `postUpgrade.behaviorChanges`, and on each
+  blocked asset `reason` plus `nextCommand`. A recorded file that is missing
+  and gitignored is `absent-local` and is recreated without consent (a
+  per-machine `.mcp.json` in a fresh worktree). A deleted file that is not
+  gitignored still needs `--accept-conflicts`. Behavior-change lines come from
+  the shipped per-version table (same sentences as these notes):
+  - 4.8.20: coverage.symbol now requires a real declaration (some green repos turn red)
+  - 4.8.21: a bare mention of an invariant id no longer counts as coverage (only describe/it titles or declarations, incl. type/interface/enum)
+  - 4.8.21: upgrade exit code 3 = applied but red. Scripts comparing against 1 must switch to 'non-zero'
+  ([#320](https://github.com/pedroknigge/arkgate/pull/320) /
+  [#311](https://github.com/pedroknigge/arkgate/issues/311),
+  [#312](https://github.com/pedroknigge/arkgate/issues/312)).
+- README first screen is the one-minute story: what (**Contener · Guiar · Ordenar**),
+  why, `npx arkgate@<version> start`, and one honest red check (fail-open named).
+  Host matrix, not-that line, and release index sit below `## Appendix`.
+  Release history points at CHANGELOG.md, the site changelog, and the docs hub.
+  ([#306](https://github.com/pedroknigge/arkgate/pull/306))
+
+### Added
+- Optional per-rule `sliceIdentity`: `path` (default) or `stars`.
+  Absent and `path` keep today's slice ids byte for byte, so baselines and
+  `allowedCrossSlice` need no migration. `stars` names a starred
+  `sliceFolders` prefix as the last literal plus the star bindings
+  (`lib/features/*/*` and `lib/repositories/features/*/*` both yield
+  `features/projects/rfi`). Doctor warns when two prefixes collapse onto one
+  id and names both paths. Additive. No `schemaVersion` bump.
+  ([#318](https://github.com/pedroknigge/arkgate/pull/318) /
+  [#308](https://github.com/pedroknigge/arkgate/issues/308)).
+
+### Fixed
+- `coverage.symbol` accepts `type`, `interface`, and `enum` declarations
+  again (a `function`, `class`, `const`, or method still counts).
+  `INVARIANT_UNCOVERED` names what the scan found — for example found `type X`
+  in a file, or that the id appears only in a comment or a test body — instead
+  of saying no symbol was declared when one was.
+  ([#319](https://github.com/pedroknigge/arkgate/pull/319) /
+  [#307](https://github.com/pedroknigge/arkgate/issues/307)).
+- Human `ark-check` groups `SHARED_IMPORTS_SLICE` advisories into one line per
+  rule and layer edge (the count and three examples) instead of one line per
+  import. The line names `ark-check --json` and `ark-check --doctor` for the
+  full list. `--json` is unchanged: one warning object per edge. Doctor prints
+  every edge. No engine change
+  ([#316](https://github.com/pedroknigge/arkgate/pull/316) /
+  [#313](https://github.com/pedroknigge/arkgate/issues/313)).
+- Doctor `pilotLoop` turns on when a pilot is proposed, including a
+  physical-cohesion reshape card on a tree that is not design-weak.
+  `summarizePilotLoop` takes one candidate list and is active only when
+  that list is non-empty. It still names **one** extraction card
+  (`nextPilot` / `extractionCard`, same fields). Further candidates stay
+  queued. Inactive reason is `no-pilot-candidates` (replaces
+  `not-design-weak` and `no-pattern-bets`). Skill completion contracts
+  derive **Incomplete?** from `doctor.productHonesty.finished`: when
+  `finished` is false, **Incomplete? no** is disallowed and the agent
+  writes `yes — <pilotLoop.extractionCard.move or residual>`
+  ([#317](https://github.com/pedroknigge/arkgate/pull/317) /
+  [#309](https://github.com/pedroknigge/arkgate/issues/309)).
+- Docs: the 4.8.20 header states its behavior change instead of "no
+  required config migration", and starred anchored `sliceFolders` wording
+  matches the code (the slice id includes the literal prefix plus the star
+  bindings) in configuration, the agent guide, and the adopt skill
+  ([#315](https://github.com/pedroknigge/arkgate/pull/315)).
+
 ## 4.8.20 — 2026-09-25
 
 **Patch** over **4.8.19**. Daily accumulate (2026-09-25 ART) of the ships
@@ -123,15 +282,20 @@ 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
+**Write. Check. Ship.** **Behavior change:** some repos that are green
+today can turn red. See the migration note under Changed. 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.
+- **Migration.** This is a behavior change. Some repos that are green today
+  will turn red when `coverage.symbol` only appeared in tests or imports.
+  Move the invariant id into a `describe`/`it` title, or point
+  `coverage.symbol` at a function, class, or const declaration; `type` and
+  `interface` symbols are currently rejected
+  ([#307](https://github.com/pedroknigge/arkgate/issues/307)).
   `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`
@@ -139,8 +303,11 @@ vitest 5 ignore
   ([#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
+  like `sharedRoots`. For a starred anchored pattern the slice id includes
+  the literal prefix plus the directories the stars bind
+  (`lib/features/projects/rfi`), so parallel trees get different ids
+  (tracked in [#308](https://github.com/pedroknigge/arkgate/issues/308)).
+  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.

package/README.md

@@ -4,53 +4,59 @@
 
 **When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.**
 
-Not an API Gateway. Not a folder linter. If the check is not required on the PR, the config
-is just documentation.
+[![Website](https://img.shields.io/badge/website-arkgate.online-0a0a0a)](https://www.arkgate.online/)
+[![CI](https://github.com/pedroknigge/arkgate/actions/workflows/ci.yml/badge.svg)](https://github.com/pedroknigge/arkgate/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/arkgate?color=cb3837&label=npm)](https://www.npmjs.com/package/arkgate)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Node](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js)
+![TS 5–7](https://img.shields.io/badge/TypeScript-5%20%7C%206%20%7C%207-3178c6?logo=typescript)
 
-AI can build fast—and make a mess just as fast.
+</div>
 
-Keep the product easy to understand, change, and trust.
+ArkGate is import rules for AI-written TypeScript. **Contener · Guiar · Ordenar**: contain what the AI may write, and in what shape. Guide the next step. Order leftover mess toward a clean tree, a little at a time.
 
-Contain what the AI may write, and in what shape. Guide you with proven patterns and one next step. Order leftover mess toward a clean tree, a little at a time.
+<a id="less-spaghetti-after-the-gate-is-green"></a>
 
-Safer changes, fewer surprises, and extra protection only when you choose it.
+## Why
 
-That is **Contener · Guiar · Ordenar**.
+AI takes the shortest path. One bad import lands, then another, and the product gets harder to change. A linter that runs only after the agent finishes sees the mess too late.
 
-Works with Cursor, Claude, Codex, and Grok.
+Design the boundary before you implement. Put a small interface in front of the work and keep the detail behind it. When leftover mess remains, the honest light is **needs a refactor**. Weakening the rules to paint the check green leaves that design unfinished.
 
-[![Website](https://img.shields.io/badge/website-arkgate.online-0a0a0a)](https://www.arkgate.online/)
-[![CI](https://github.com/pedroknigge/arkgate/actions/workflows/ci.yml/badge.svg)](https://github.com/pedroknigge/arkgate/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/arkgate?color=cb3837&label=npm)](https://www.npmjs.com/package/arkgate)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-![Node](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js)
-![TS 5–7](https://img.shields.io/badge/TypeScript-5%20%7C%206%20%7C%207-3178c6?logo=typescript)
+## Try it
+
+One command. Preview only — no files change. Current release is **4.8.22**
+(check npm `latest` with `npm view arkgate version`):
+
+```bash
+npx arkgate@4.8.22 start
+```
+
+## What a red result looks like
+
+After a rules file exists, a domain file that imports infrastructure fails the check (exit 1). This is real output from `arkgate-check` on arkgate@4.8.20:
 
 ```text
-  ┌─────────┐     ┌─────────┐     ┌─────────┐
-  │  WRITE  │────▶│  CHECK  │────▶│  SHIP   │
-  │  agent  │     │  block  │     │  merge  │
-  └─────────┘     └────┬────┘     └─────────┘
-                       │
-                       ▼
-                 bad import
-                 doesn't land
+✖ LAYER_IMPORT_VIOLATION  src/domain/order.ts:1
+  DomainModel → Infrastructure  (src/infra/db.ts)
+  DomainModel must not import Infrastructure.
+  Next action: Classify the import: if it is constants/types/pure, adopt into DomainModel or SharedKernel; define a port only if the target is a real use-case. Then preflight again.
+
+✖ 1 violation(s).
 ```
 
-</div>
+Do that next action. Classify the import, or introduce a port when the dependency is a real use case. Then run the check again.
+
+That red line is the check. It does not stop every write. On Cursor, a hook without `failClosed: true` is fail-open: if the checker cannot run, the write still lands. Shell writes, hosted tools, and human edits are outside the local hook. The hard line for every path is a **required** GitHub status running `arkgate-check --strict-merge`. Until that status is required, the rules file is just documentation.
 
-> **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**
-> (`arkgate/runtime`) is an in-memory runtime — not Postgres. Optional **ArkOrder**
-> (`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.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)
+Anyone: [Use ArkGate](docs/use.md) · Developers: [Develop](docs/develop.md) · This library: [CONTRIBUTING](CONTRIBUTING.md)
 
 ---
 
+## Appendix
+
+The minute above is the product. Below is reference: the longer introduction, what this is not, hosts, commands, extras, and where release history lives.
+
 ## Choose your path
 
 | You are… | Go here |
@@ -61,47 +67,26 @@ Works with Cursor, Claude, Codex, and Grok.
 
 Full map: **[docs/README.md](docs/README.md)**
 
----
-
-## Start in one minute
+## The longer introduction
 
-```bash
-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
-```
+AI can build fast—and make a mess just as fast.
 
-`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.
+Keep the product easy to understand, change, and trust.
 
-`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
-planned write is too big for compact start (more than 8 gate files or 32 KB).
-That lock is deliberate. Coverage/shape: lock with `--archetype <id>`,
-`--preset <name>`, or `--force`. Size: `--force` does not unlock. Next:
-`npx arkgate-check --init`. Or inspect ranked shapes with
-`npx arkgate-check --recommend`.
+Contain what the AI may write, and in what shape. Guide you with proven patterns and one next step. Order leftover mess toward a clean tree, a little at a time.
 
-That is the product. Stuck? Run status (`--doctor`) and do action **#1**.
+Safer changes, fewer surprises, and extra protection only when you choose it.
 
-```text
-start → doctor → new files in the right folder
-              ↘ leftover mess: map, then one small refactor
-```
+That is **Contener · Guiar · Ordenar**.
 
-Keep the rules file out of product PRs. Local check:
-`ark-check --local --base origin/dev` (same as `--changed`; refused with
-`--strict-merge`). Changing the rules themselves uses `--contract-session`.
+## What this is not
 
-Aliases `ark` / `ark-check` / `ark-mcp` still work. npm / pnpm / yarn. No install lifecycle scripts
-— and none on pack or prepare either, so `pnpm add git+https://github.com/pedroknigge/arkgate`
-installs at a pinned commit with no `allowBuilds` entry. A git install gives you the CLIs and the
-schemas; the library, MCP and ESLint entry points live in the built `dist/` and come from npm.
-See [docs/package-surface.md](docs/package-surface.md#installing-from-git).
+Not an API Gateway. Not a folder linter. If the check is not required on the PR, the config
+is just documentation.
 
-![Write gate: agent blocked, then self-corrects](docs/assets/ark-write-gate.svg)
+ArkGate is not a web framework, ORM, or job runner. The npm package is `arkgate` — not affiliated with the separate Archgate CLI project.
 
----
+ArkRun is an optional experimental runtime. In-memory. Not Postgres. `@arkgate/runtime` is deprecated. ArkOrder does not replace import rules: layers can be green while the agent still rewrites the billing plan like a seat count.
 
 ## What it is
 
@@ -133,12 +118,20 @@ inter-layer verdict when absent. Label leftovers **`[Layer]`** vs **`[ArkRules]`
 **`[ArkRun]`** vs **`[ArkOrder]`**.
 Details: [configuration](docs/configuration.md) · [use](docs/use.md).
 
-**Not** an API Gateway, a folder linter, a web framework, ORM, or job runner.
-ArkRun is in-memory — local and tests, not Postgres. ArkOrder does not replace
-import rules: layers can be green while the agent still PATCHes the billing plan
-like a seat count.
+```text
+  ┌─────────┐     ┌─────────┐     ┌─────────┐
+  │  WRITE  │────▶│  CHECK  │────▶│  SHIP   │
+  │  agent  │     │  block  │     │  merge  │
+  └─────────┘     └────┬────┘     └─────────┘
+                       │
+                       ▼
+                 bad import
+                 doesn't land
+```
+
+![Write gate: agent blocked, then self-corrects](docs/assets/ark-write-gate.svg)
 
-**Name note:** npm package `arkgate` — not affiliated with the separate Archgate CLI project.
+Adopted means a required GitHub status running `arkgate-check --strict-merge`, or an explicit `advisory-only` stance. Status is compact (`arkgate-check --doctor`; `--all` for details).
 
 ### When not to adopt
 
@@ -152,18 +145,6 @@ check: [4.3.0 — What ArkGate is / isn't](docs/releases/4.3.0.md#what-arkgate-i
 
 ---
 
-## Why it exists
-
-AI takes the shortest path. Contain the write so a bad import never lands. Guide
-the next step so a non-expert is not stuck. Order leftover mess toward a clean
-tree, one small refactor at a time.
-
-Traditional linters catch this only in CI after the agent finished. ArkGate
-checks at write time and again on the PR. Green imports are not elegant design —
-leftover mess is **needs a refactor**, not “done”.
-
----
-
 ## Status lights (not settings)
 
 ```text
@@ -183,6 +164,44 @@ Details: [docs/use.md](docs/use.md).
 
 ---
 
+## Start in one minute
+
+```bash
+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
+```
+
+`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
+planned write is too big for compact start (more than 8 gate files or 32 KB).
+That lock is deliberate. Coverage/shape: lock with `--archetype <id>`,
+`--preset <name>`, or `--force`. Size: `--force` does not unlock. Next:
+`npx arkgate-check --init`. Or inspect ranked shapes with
+`npx arkgate-check --recommend`.
+
+That is the fuller path. Stuck? Run status (`--doctor`) and do action **#1**.
+
+```text
+start → doctor → new files in the right folder
+              ↘ leftover mess: map, then one small refactor
+```
+
+Keep the rules file out of product PRs. Local check:
+`ark-check --local --base origin/dev` (same as `--changed`; refused with
+`--strict-merge`). Changing the rules themselves uses `--contract-session`.
+
+Aliases `ark` / `ark-check` / `ark-mcp` still work. npm / pnpm / yarn. No install lifecycle scripts
+— and none on pack or prepare either, so `pnpm add git+https://github.com/pedroknigge/arkgate`
+installs at a pinned commit with no `allowBuilds` entry. A git install gives you the CLIs and the
+schemas; the library, MCP and ESLint entry points live in the built `dist/` and come from npm.
+See [docs/package-surface.md](docs/package-surface.md#installing-from-git).
+
+---
+
 ## Host enforcement support
 
 <!-- arkgate-host-support:start -->
@@ -271,6 +290,10 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok,antigra
 
 More: [docs/develop.md](docs/develop.md) · skills install: [docs/agent-guide.md](docs/agent-guide.md#install-skills-ark-and-ecosystem) · enthusiast track: [docs/enthusiast/](docs/enthusiast/README.md)
 
+## Other skills, only when you need them
+
+Day-to-day work uses the compact router and status. The full `/ark-*` pack is expert depth: install it when you want a guided next step, not as the first action. Catalog and install paths: [Install skills — Ark and ecosystem](docs/agent-guide.md#install-skills-ark-and-ecosystem).
+
 ---
 
 ## Optional ArkRun
@@ -346,44 +369,11 @@ 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.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) |
-| Prior published (4.8.7) | [docs/releases/4.8.7.md](docs/releases/4.8.7.md) · [CHANGELOG](CHANGELOG.md) |
-| Prior published (4.8.6) | [docs/releases/4.8.6.md](docs/releases/4.8.6.md) |
-| Prior published (4.8.5) | [docs/releases/4.8.5.md](docs/releases/4.8.5.md) |
-| Prior published (4.8.4) | [docs/releases/4.8.4.md](docs/releases/4.8.4.md) |
-| Prior published (4.8.3) | [docs/releases/4.8.3.md](docs/releases/4.8.3.md) |
-| Prior published (4.8.2) | [docs/releases/4.8.2.md](docs/releases/4.8.2.md) |
-| Prior published (4.8.1) | [docs/releases/4.8.1.md](docs/releases/4.8.1.md) |
-| Prior published (4.8.0) | [docs/releases/4.8.0.md](docs/releases/4.8.0.md) |
-| Prior published (4.7.6) | [docs/releases/4.7.6.md](docs/releases/4.7.6.md) |
-| Prior published (4.7.5) | [docs/releases/4.7.5.md](docs/releases/4.7.5.md) |
-| Prior published (4.7.3) | [docs/releases/4.7.3.md](docs/releases/4.7.3.md) |
-| Prior published (4.7.2) | [docs/releases/4.7.2.md](docs/releases/4.7.2.md) |
-| Prior published (4.7.1) | [docs/releases/4.7.1.md](docs/releases/4.7.1.md) |
-| Prior published (4.7.0) | [docs/releases/4.7.0.md](docs/releases/4.7.0.md) |
-| Prior published (4.6.7) | [docs/releases/4.6.7.md](docs/releases/4.6.7.md) |
-| Prior published (4.6.6) | [docs/releases/4.6.6.md](docs/releases/4.6.6.md) |
-| Prior published (4.6.5) | [docs/releases/4.6.5.md](docs/releases/4.6.5.md) |
-| Prior published (4.6.3) | [docs/releases/4.6.3.md](docs/releases/4.6.3.md) |
-| Prior (4.6.2) | [docs/releases/4.6.2.md](docs/releases/4.6.2.md) |
-| Prior (4.6.1) | [docs/releases/4.6.1.md](docs/releases/4.6.1.md) |
-| Prior (4.6.0) | [docs/releases/4.6.0.md](docs/releases/4.6.0.md) |
-| Prior (4.5.7) | [docs/releases/4.5.7.md](docs/releases/4.5.7.md) |
-| Prior (4.5.0) | [docs/releases/4.5.0.md](docs/releases/4.5.0.md) |
-| Prior (4.4.0) | [docs/releases/4.4.0.md](docs/releases/4.4.0.md) |
-| Prior (4.3.0) | [docs/releases/4.3.0.md](docs/releases/4.3.0.md) |
-| Prior (4.2.1) | [docs/releases/4.2.1.md](docs/releases/4.2.1.md) |
-| Previous (4.2.0) | [docs/releases/4.2.0.md](docs/releases/4.2.0.md) |
-| Previous (4.1.1) | [docs/releases/4.1.1.md](docs/releases/4.1.1.md) |
-| Previous (4.1.0) | [docs/releases/4.1.0.md](docs/releases/4.1.0.md) |
-| Previous patch (4.0.1) | [docs/releases/4.0.1.md](docs/releases/4.0.1.md) |
-| Previous (4.0.0) | [docs/releases/4.0.0.md](docs/releases/4.0.0.md) |
-| Previous (3.9.2) | [docs/releases/3.9.2.md](docs/releases/3.9.2.md) |
+| Release history | [CHANGELOG.md](CHANGELOG.md) · [site changelog](https://www.arkgate.online/changelog/) · [docs hub index](docs/README.md#history-and-maintainer-material) |
 | History / maintainer evidence | [docs/archive/](docs/archive/README.md) |
 
+Version notes live in [CHANGELOG.md](CHANGELOG.md) and on the [site changelog](https://www.arkgate.online/changelog/). The docs hub keeps the per-version index: [History and maintainer material](docs/README.md#history-and-maintainer-material).
+
 ---
 
 ## Contribute to this library

package/bin/ark-check-runtime.mjs

@@ -74,7 +74,7 @@ import {
   writeBaseline,
   printViolation,
   printViolationBreakdown,
-  printWarning,
+  printHumanWarnings,
   CONCENTRATION_MIN_VIOLATIONS,
 } from './lib/violations.mjs';
 import {
@@ -1503,6 +1503,7 @@ async function main() {
       safety, designDelta,
       ts, parseHealth, completeness,
       all: args.all === true, requireGates: args.requireGates === true,
+      warnings,
     });
     if (designDelta) process.exitCode = !designDelta.complete ? 2 : designDelta.valid ? 0 : 1; return;
   }
@@ -1956,9 +1957,7 @@ async function main() {
       ...(teamParliament ? { teamParliament } : {}),
     }, null, 2));
   } else {
-    for (const warning of warnings) {
-      printWarning(warning);
-    }
+    printHumanWarnings(warnings);
     for (const violation of activeViolations) {
       printViolation(violation);
     }