arkgate 4.8.19 → 4.8.21

package/CHANGELOG.md

@@ -96,6 +96,226 @@ 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.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
+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.** **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
+- **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`
+  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`. 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.
+  `src/components/features/projects/rfi-status-pill.tsx` with `["projects"]`
+  is not a slice. Bare names under `src/lib/features` behave exactly as
+  before: `src/lib/features/projects/rfi/x.ts` with `["features"]` stays
+  `features/projects` (a regression test covers it)
+  ([#300](https://github.com/pedroknigge/arkgate/pull/300) /
+  [#294](https://github.com/pedroknigge/arkgate/issues/294)).
+
+### Fixed
+- Reshape pilot destinations stay in the source file's layer and slice. A
+  proposal that would leave both is withheld instead of pointing at
+  `src/features/`
+  ([#299](https://github.com/pedroknigge/arkgate/pull/299) /
+  [#295](https://github.com/pedroknigge/arkgate/issues/295)).
+- Doctor no longer calls the tree finished or elegant while a
+  physical-cohesion finding is still unsuppressed. The gate verdict is
+  unchanged, and the reshape card stays one judgment
+  ([#302](https://github.com/pedroknigge/arkgate/pull/302) /
+  [#296](https://github.com/pedroknigge/arkgate/issues/296)).
+- A `peerIsolation` rule may set `sharedImportsSlice` to `"deny"`. A
+  declared shared root then may not import a slice
+  (`shared root … → slice …`). The default stays off, so current walls
+  stay green. A slice importing a shared root stays allowed.
+  `allowedCrossSlice` does not excuse this hop. Doctor lists shared-root
+  → slice bridges even when the flag is off. A green run still says the
+  wall is direct-only
+  ([#303](https://github.com/pedroknigge/arkgate/pull/303) /
+  [#297](https://github.com/pedroknigge/arkgate/issues/297)).
+- Age-gated `start --apply` install failure no longer reprints the same
+  `pnpm add` as the primary next step. Recovery names pnpm Age, leads
+  with `npx --package=arkgate@<pin> arkgate-check --doctor`, and says
+  `minimumReleaseAgeExclude` must live in pnpm config or
+  `pnpm-workspace.yaml` (a CLI flag is not enough)
+  ([#293](https://github.com/pedroknigge/arkgate/pull/293) /
+  [#292](https://github.com/pedroknigge/arkgate/issues/292)).
+
+### Dependencies
+- Dev dependency `vitest` and `@vitest/coverage-v8` are on 4.1.11, which
+  pulls `@vitest/mocker@4.1.11` and closes
+  [GHSA-82fw-gwwq-j7x9](https://github.com/vitest-dev/vitest/security/advisories/GHSA-82fw-gwwq-j7x9)
+  (moderate path traversal via redirect mocks). Vitest 4's V8 coverage
+  provider remaps with AST analysis, so the same suite reports a larger
+  branch denominator; coverage floors moved to just under those measured
+  numbers. No tests were removed
+  ([#298](https://github.com/pedroknigge/arkgate/pull/298)).
+- Dependabot ignores vitest 5 (`vitest`, `@vitest/coverage-v8`, and
+  `@vitest/mocker` at `>= 5.0.0`) until Node 22.12+ is the floor.
+  Version-update pull requests stay off; the cooldown is 7 days
+  ([#304](https://github.com/pedroknigge/arkgate/pull/304)).
+- Docs: anonymized live dogfood sales stats
+  ([#244](https://github.com/pedroknigge/arkgate/pull/244)); `UC01` marked
+  done after [#233](https://github.com/pedroknigge/arkgate/pull/233)
+  ([#234](https://github.com/pedroknigge/arkgate/pull/234)).
+
 ## 4.8.19 — 2026-09-20
 
 **Patch** over **4.8.18**. Daily accumulate (2026-09-20 ART) of the five

package/README.md

@@ -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.21**
+(check npm `latest` with `npm view arkgate version`):
+
+```bash
+npx arkgate@4.8.21 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.
 
-> **ArkGate 4.8.19** 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.19](CHANGELOG.md) · [4.8.11](docs/releases/4.8.11.md) · [4.8.10](docs/releases/4.8.10.md) · [4.8.9](docs/releases/4.8.9.md) · [4.8.8](docs/releases/4.8.8.md) · [4.8.7](docs/releases/4.8.7.md) · [4.8.6](docs/releases/4.8.6.md) · [4.8.5](docs/releases/4.8.5.md) · [4.8.4](docs/releases/4.8.4.md) · [4.8.3](docs/releases/4.8.3.md) · [4.8.2](docs/releases/4.8.2.md) · [4.8.1](docs/releases/4.8.1.md) · [4.8.0](docs/releases/4.8.0.md) · [Docs hub](docs/README.md) · [Voice](docs/product-voice.md)
+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.
+
+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.
+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.19 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;
   }
@@ -1673,6 +1674,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 +1704,7 @@ async function main() {
         notAScore: true,
       },
       nextPilot: nextPilot,
+      ...(coverageEvidence ? { coverageEvidence } : {}),
     };
     if (args.json) {
       console.log(JSON.stringify(payload, null, 2));
@@ -1695,6 +1718,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;
@@ -1933,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);
     }