arkgate 4.8.13 → 4.8.15

package/CHANGELOG.md

@@ -5,6 +5,218 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+### Added
+- Soft doctor residual when Domain is declared but empty and the UI holds the
+  rules (`noDomainFrontend`). Projects empty Domain + presentation share, or
+  the existing `domain-logic-in-ui` smell. Friendly next step: one Domain file
+  (`/ark-place`) then one small refactor. Not a fail. Silent when there is no
+  frontend, Domain already has files, or the UI bag is too thin. No new skill,
+  schema, smell id, or config key.
+- Narrow opt-in status/transition catalog: when Domain-role code already
+  names a closed status/state vocabulary and a domain doc is in play without
+  a table (or one link), doctor JSON may add `statusTransitionCatalog` with
+  those names. Friendly next step. Not a fail. Silent when Domain has no
+  status vocabulary, or the domain doc is absent, or the map is already
+  present. No new skill, schema, or config key.
+- Doctor residual when a product-domain doc is already in play
+  (`docs/domain.md` or a sibling) and there is no states → transitions table
+  (or one link) yet. Friendly next step. Not a fail. Silent when that doc is
+  absent. No new skill, schema, or status-field sensor.
+- Soft ADR / decision-note presence when `--require-gates` (or
+  `--strict` / `--strict-merge` / doctor adopted-strict) is on and the tree
+  has no `docs/adr/` or `docs/decisions/` note yet. Doctor residual + a
+  friendly next step. Not a fail. Silent when require-gates is off. No new
+  skill, schema, or config key. Policy weaken still uses `--policy-ack`.
+- Optional `layers[].owners` on each layer (GitHub handle or email, same
+  identity as `stewards`) and optional `requireLayerOwners`. Absence is
+  silent. When the require flag is on, doctor names the first house without
+  an owner, `--strict-config` refuses, and the write gate denies a write into
+  that house. Owners are stripped from `policyHash`; the require flag stays
+  in the hash. Invalid identity fails the schema. No new skill or
+  `schemaVersion` bump. Compact starters may omit.
+- Optional `layers[].trustBoundary` on each layer: `public` | `auth` | `admin` |
+  `internal`. Who this folder is for. Schema validates the closed list; a wrong
+  value fails. Absence is silent — never a doctor residual, never
+  `--strict-config`, never a score. Place / prepare-write / MCP / doctor /
+  coverage / HTML show `trust: public` when present. Stripped from `policyHash`
+  like `stewards` and `layers[].description`. No import-rule matrix. Not host/CI
+  TLS. No new skill or `schemaVersion` bump. Compact starters may omit.
+- Doctor residual when `arkRules` is on, Domain has code, and `invariants[]` is
+  empty (`INVARIANT_CATALOG_EMPTY`). Points at the file to fill. Advisory unless
+  a domain structure rule is already enforced — then `--strict-merge` can refuse.
+  No `arkRules` map, or no Domain files, stays silent. Domain starters ship two
+  short phrase templates so the shape is visible. No new skill, schema, or flag.
+
+### Changed
+- Compact `--doctor` names ArkRules only when the `arkRules` map is on
+  (one breath + counts, not a score). Absence stays silent. Reuses
+  `rulesUnderContract` — no new schema, flag, or skill. `--doctor --all`
+  prints the same lines under **ArkRules (not a score)**.
+- PR / CI skill gate: `npm run check:agent-skills` now fails closed when a
+  product plane (Layers, ArkRules, ArkRun, ArkOrder) or Contener · Guiar ·
+  Ordenar drops out of first-class skill bodies or living hubs. Reuses
+  `ARK_SKILL_CAPACITY` via Domain `validateSkillProductCapacity` — no new
+  schema or skill. Deny copy stays plain. Skills never enforce.
+- Write-gate host parity: Cursor hard-write evidence now requires the host-native
+  `failClosed: true` flag (same idea as a file permission — if the checker cannot
+  run, the write must not land). A Write/StrReplace hook without that flag is
+  fail-open: doctor, `--require-write-hook`, and honesty JSON say so and do not
+  claim a hard block. Hosts without a native flag stay as before (deny when the
+  hook runs; hook-crash behavior is host-owned). Soft hosts stay advisory.
+  Required CI is still the shared merge line. No new skill, schema, or host.
+
+### Fixed
+- Write hook and `ark-check` now agree on overlapping layer globs: the hook
+  probes the same specifier extensions as `ark-check` and classifies with
+  `layerForRelativePath` (explicit `money.ts` beats `src/lib/**`). Field
+  case: Persistence importing `@/lib/finance/money` is allowed when the
+  contract says DomainModel, not denied as ApplicationOrchestration
+  (issue [#237](https://github.com/pedroknigge/arkgate/issues/237)).
+  `LEXICAL_EVIDENCE_INCOMPLETE` no longer calls the hook the final verdict —
+  `ark-check` is the authority. No new schema, flag, or skill.
+- An `include` that matches files but classifies none of them no longer prints
+  a green check. `ANALYSIS_COVERS_NO_FILES` already said include **and** layer;
+  the refusal now counts classified files, not only the include walk. The write
+  hook denies those same files (`CONFIG_UNCLASSIFIED_FILES`) so write and
+  `--strict-merge` agree. Partial unclassified stays a warning on a plain check.
+  `--plan` / `--coverage` / `--doctor` still diagnose. No new flag or schema.
+- Library / package-monorepo `arkgate start` no longer writes Next App Router /
+  Pages API / `app/api` layer captions when the tree has no Next
+  (issue [#213](https://github.com/pedroknigge/arkgate/issues/213)). Next-flavored
+  doctor copy still appears when Next is detected. Same start command; no new flag.
+- Cold `--doctor` no longer treats a full governed list as a `--changed` scope
+  (issue [#212](https://github.com/pedroknigge/arkgate/issues/212)). Full-tree
+  status uses the unbounded facts path; import-closure + a second
+  `resolveModuleName` pass stay on `--changed` only. Extra-plane extractors
+  (ArkRun / ArkOrder / class-shape) stay silent when that plane is off. Same
+  compact first screen. No new flag or cache.
+- Fresh `arkgate start --apply` (and every other path that stamps a new
+  `ark.config.json`) now writes `$schema` at `arkgate@4` on unpkg, not the stale
+  `@2` pin (issue [#211](https://github.com/pedroknigge/arkgate/issues/211)).
+  Existing configs keep whatever URL they already have. Editor completion
+  matches the 4.x line you just installed.
+
+## 4.8.15 — 2026-09-13
+
+**Patch** over **4.8.14**. Pre-adoption ship bar: opt-in `--local` /
+`ARK_CHECK_LOCAL` cheap multi-worktree check
+([#251](https://github.com/pedroknigge/arkgate/pull/251)) and dogfood
+honesty
+([#252](https://github.com/pedroknigge/arkgate/pull/252) / [#243](https://github.com/pedroknigge/arkgate/issues/243) /
+[#246](https://github.com/pedroknigge/arkgate/issues/246) /
+[#247](https://github.com/pedroknigge/arkgate/issues/247)).
+**Write. Check. Ship.** **No required config migration.** No
+`schemaVersion` bump. Does not close `K01` / `Z09`. This mother
+`ark.config.json` still does **not** turn `arkOrder` on.
+
+**Status: prepared** (npm `latest` remains **4.8.14** until Actions `publish-npm`
+runs with `tag=v4.8.15` and `dry_run=false`).
+
+### Added
+- Opt-in local / multi-worktree cheap check: `--local` or `ARK_CHECK_LOCAL=1`
+  reuses `--changed` (touched files + import closure) and stays per `--root`.
+  Explicit `--local --strict-merge` is refused so CI Contener stays fail-closed.
+  The env var is ignored under `--strict-merge` and under `--doctor` /
+  `--coverage` / `--plan` / `--report` / `--promote`. JSON may add `local`,
+  `scope: "changed"`, `analysisRoot`. Write hooks stay lexical. No new schema,
+  cache, skill, or second analysis engine. Design:
+  [docs/plans/local-check-worktree-dx/README.md](docs/plans/local-check-worktree-dx/README.md).
+
+### Fixed
+- Publish confidence gate: retarget drifted critical mutation islands
+  (`config-loading`, `empty-analysis-refusal`, host fail-open / none-gap)
+  after owners + classified-file growth, and add tests that kill those
+  mutants. Threshold stays 90% with zero NoCoverage. Does not change
+  runtime behavior.
+- Dogfood honesty: type-only `LAYER_IMPORT_VIOLATION` prints `⚠` (not `✖`)
+  when the check still exits 0 ([#243](https://github.com/pedroknigge/arkgate/issues/243));
+  one-minute `start --apply` copy and the start preview footer name the
+  deliberate lock flags (`--archetype`, `--preset`, `--force`,
+  `ark-check --recommend`) without softening the refuse gate
+  ([#246](https://github.com/pedroknigge/arkgate/issues/246)); start,
+  `--recommend`, and doctor share one `computeCoverage` definition of
+  projected governed coverage
+  ([#247](https://github.com/pedroknigge/arkgate/issues/247)).
+
+## 4.8.14 — 2026-09-06
+
+**Patch** over **4.8.13**. Catch npm `latest` up to `main`: first-class
+`/ark-order` (#217 / #216) and the other ships that landed after tag
+`v4.8.13`. **Write. Check. Ship.** **No required config migration.** No
+`schemaVersion` bump. Does not close `K01` / `Z09`. This mother
+`ark.config.json` still does **not** turn `arkOrder` on.
+
+**Status: prepared** (npm `latest` remains **4.8.13** until Actions `publish-npm`
+runs with `tag=v4.8.14` and `dry_run=false`).
+
+### Added
+- Skill catalog covers 100% of product capacity (issue [#216](https://github.com/pedroknigge/arkgate/issues/216) /
+  [ADR 0036](docs/adr/0036-skill-catalog-product-capacity.md) / [#217](https://github.com/pedroknigge/arkgate/pull/217)).
+  First-class `/ark-order` mirrors `/ark-runtime` for ArkOrder. Leftover
+  `/ark-architect` / `/ark-contract` / `/ark-fix` / `/ark-loop` / `/ark-think`
+  stay as one-release redirect stubs. Remaining doors speak Contener · Guiar ·
+  Ordenar and name the sibling for each job. ACS05 “no new skill names” freeze
+  opened; the catalog stays closed in Domain (`ARK_SKILL_NAMES`). Leftover
+  `/ark-fix` / `/ark-loop` stubs keep the Y04 mechanical-edit hygiene outcomes.
+  Skills never enforce.
+
+### Changed
+- First-contact leftovers after the north-star / billing / one-breath ships
+  ([#225](https://github.com/pedroknigge/arkgate/pull/225)): gallery index and
+  the hexagonal demo open in ordinary English; `arkgate-check --help` leads with
+  the deny; the write-gate fallback and the two newcomer deny codes
+  (`LAYER_IMPORT_VIOLATION`, `ARKORDER_UNVALVED_RELEASE`) drop ξ /
+  “architecture contract” from the first line.
+- Doctor / start first-contact always tell the ArkOrder one-breath (what it
+  is, when to use it, next step) even when the extra is off ([#224](https://github.com/pedroknigge/arkgate/pull/224)).
+  Reuses `/ark-order` and `examples/arkorder-billing`. Verdicts stay silent (not a
+  score; Layers unchanged).
+- First-contact now names **Contener · Guiar · Ordenar** in ordinary English
+  (contain the write, guide the next step, order leftover mess)
+  ([#222](https://github.com/pedroknigge/arkgate/pull/222)). README, doctor
+  one-light, CLI help, host projections, and first-class skills share the same
+  breath. Write. Check. Ship. stays the deny.
+- Billing gallery is the undeniable ArkOrder proof path
+  ([#223](https://github.com/pedroknigge/arkgate/pull/223)): site/docs
+  (`docs/use.md`, docs hub, enthusiast) →
+  [examples/README.md](https://github.com/pedroknigge/arkgate/blob/main/examples/README.md)
+  → [examples/arkorder-billing](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing)
+  (first freeze `release()`, later `proposeRelease` then `apply`). Still GitHub-only;
+  not added to the npm tarball or `GALLERY_STARTERS`.
+- Living docs (AGENTS hub, claims matrix, agent-guide skill install, product-voice
+  filter) restate the catalog after `#217`: first-class `/ark-order`, leftover
+  shortcuts as one-release stubs, ACS05 freeze opened, Domain still closes
+  `ARK_SKILL_NAMES`. The skill *set* covers Layers + ArkRules + ArkRun + ArkOrder
+  (Contener · Guiar · Ordenar). Historical 14/14 100% and last 4.8.3 C-020 stay
+  Planned.
+- Pre-adoption publish is the thin path: slim CI on prepare PRs (no `release`
+  label or branch-name full-matrix), annotated tags (unsigned allowed),
+  CHANGELOG + `publish-npm` provenance. MCP registry, site, companion republish,
+  and `docs/releases/` notes stay optional.
+
+### Fixed
+- `--changed` no longer builds facts for the whole include tree (issue
+  [#205](https://github.com/pedroknigge/arkgate/issues/205) /
+  [#221](https://github.com/pedroknigge/arkgate/pull/221)). The check now
+  resolves touched sources plus their import closure, skips the unused
+  tsconfig file walk, and does not list every governed file just to filter
+  the diff. File-local ArkRules sensors stay on the touched set. Full-tree
+  `ark-check` is unchanged. Dual gate (write + PR) stays the merge line.
+- Short `arkgate-check --help` now names `--changed --base <ref>` as the local /
+  pre-push fast path (issue [#204](https://github.com/pedroknigge/arkgate/issues/204) /
+  [#220](https://github.com/pedroknigge/arkgate/pull/220)).
+  Encyclopedia `--help --all` is unchanged.
+- `ark-check` human warnings now print `path:line` the way denies already do
+  (ArkOrder / ArkRun advisory findings already carried the location; the
+  printer dropped it). Findings with no file say so — they are about the
+  project rules, not a line you just edited. The green `--plan` pointer names
+  the first evidence path next to each design smell (issue #203).
+- `start --apply` / `--install-agent-gates` now merge the Ark write-path
+  contract into a project-owned `AGENTS.md` and upsert `mcpServers.ark` in
+  existing `.mcp.json` (and host copies) without `--force`. Doctor no longer
+  reports `gatesMissing: ["AGENTS.md", ".mcp.json"]` after the stranger happy
+  path on a repo that already had those files (issue #210).
+
 ## 4.8.13 — 2026-09-06
 
 **Patch** over **4.8.12**. Publish gate: remaining ArkOrder doctor/deny branches so
@@ -13,8 +225,9 @@ this is the ship. **Write. Check. Ship.** **No required config migration.** No
 `schemaVersion` bump. Does not close `K01` / `Z09`. No new skill names. This
 mother `ark.config.json` still does **not** turn `arkOrder` on.
 
-**Status: prepared** (tree candidate; npm `latest` remains **4.8.11** until the
-signed-tag provenance workflow succeeds).
+**Status: prepared** (tag `v4.8.13` and the GitHub Release already exist;
+npm `latest` remains **4.8.11** until Actions `publish-npm` runs with
+`tag=v4.8.13` and `dry_run=false`).
 
 ### Fixed
 - Confidence coverage: remaining ArkOrder doctor/deny `Next:` and HTML/doctor
@@ -29,8 +242,10 @@ them through doctor / start / status / the check label, in plain words.
 Does not close `K01` / `Z09`. No new skill names. This mother `ark.config.json`
 still does **not** turn `arkOrder` on.
 
-**Status: prepared** (tree candidate; npm `latest` remains **4.8.11** until the
-signed-tag provenance workflow succeeds).
+**Status: tagged, not published** (tag `v4.8.12` stands; `publish-npm` failed
+the 81% branch floor at 80.97%. Do not retag. Do not ship this version to npm.
+Consumers stay on **4.8.11** until **4.8.13** is published.
+npm `latest` remains **4.8.11**).
 
 ### Added
 - Doctor / HTML / status `arkOrder` section (`notAScore`), same envelope as

package/README.md

@@ -11,10 +11,12 @@ AI can build fast—and make a mess just as fast.
 
 Keep the product easy to understand, change, and trust.
 
-ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+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.
 
 Safer changes, fewer surprises, and extra protection only when you choose it.
 
+That is **Contener · Guiar · Ordenar**.
+
 Works with Cursor, Claude, Codex, and Grok.
 
 [![Website](https://img.shields.io/badge/website-arkgate.online-0a0a0a)](https://www.arkgate.online/)
@@ -37,7 +39,7 @@ Works with Cursor, Claude, Codex, and Grok.
 
 </div>
 
-> **ArkGate 4.8.13** is prepared on this tree; npm `latest` remains **4.8.11**.
+> **ArkGate 4.8.15** is prepared on this tree; npm `latest` remains **4.8.14** until `publish-npm` for `v4.8.15`.
 > 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**
@@ -45,7 +47,7 @@ Works with Cursor, Claude, Codex, and Grok.
 > (`arkgate/order`) stops rewriting a big product choice — like the billing plan —
 > as if it were a seat count. Change those choices through a valve, not a generic update.
 > `@arkgate/runtime` is deprecated.
-> [4.8.13 prepared](CHANGELOG.md) · [4.8.11 published](docs/releases/4.8.11.md) · [4.8.10](docs/releases/4.8.10.md) · [4.8.9](docs/releases/4.8.9.md) · [4.8.8](docs/releases/4.8.8.md) · [4.8.7](docs/releases/4.8.7.md) · [4.8.6](docs/releases/4.8.6.md) · [4.8.5](docs/releases/4.8.5.md) · [4.8.4](docs/releases/4.8.4.md) · [4.8.3](docs/releases/4.8.3.md) · [4.8.2](docs/releases/4.8.2.md) · [4.8.1](docs/releases/4.8.1.md) · [4.8.0](docs/releases/4.8.0.md) · [Docs hub](docs/README.md) · [Voice](docs/product-voice.md)
+> [4.8.15 prepared](CHANGELOG.md) · [4.8.11 published](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)
 
 ---
 
@@ -71,6 +73,11 @@ npx arkgate-check --doctor        # status — one next step
 npx arkgate-check --doctor --all  # full details
 ```
 
+`start --apply` refuses when projected governed coverage is below 50% or
+shape confidence is weak (below 0.6 with coverage under 80%). That lock is
+deliberate. Lock the shape with `--archetype <id>`, `--preset <name>`, or
+`--force`, or inspect ranked shapes with `npx arkgate-check --recommend`.
+
 That is the product. Stuck? Run status (`--doctor`) and do action **#1**.
 
 ```text
@@ -79,7 +86,8 @@ start → doctor → new files in the right folder
 ```
 
 Keep the rules file out of product PRs. Local check:
-`ark-check --changed --base origin/dev`. Changing the rules themselves uses `--contract-session`.
+`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`
@@ -106,15 +114,15 @@ See [docs/package-surface.md](docs/package-surface.md#installing-from-git).
 
 When the agent writes a bad import, the write doesn’t land.
 The same check fails the pull request. That is **ArkGate** — import rules, always on
-once you adopt. The other three are optional.
+once you adopt (**Contener**). The other three are optional.
 
 | | Role | When |
 |--|------|------|
 | **While the agent writes** | The write doesn’t land on supported hosts; warning only elsewhere | Always (ArkGate) |
 | **Before merge** | `arkgate-check` as a **required** CI status | Always (ArkGate) |
-| **ArkRules** | Optional policies *inside* a layer | When you ask |
-| **ArkRun** | Optional experimental runtime (`arkgate/runtime`) | Off unless you turn it on |
-| **ArkOrder** | Stops rewriting a big product choice (like billing plan) as if it were a seat count. Change it through a valve, not a generic update (`arkgate/order`) | Off unless you turn it on |
+| **ArkRules** | Optional policies *inside* a layer (**Contener** — shape) | When you ask |
+| **ArkRun** | Optional experimental runtime (`arkgate/runtime`) (**Guiar**) | Off unless you turn it on |
+| **ArkOrder** | Extra for the few big choices — billing plan, not seat counts (`arkgate/order`) (**Ordenar**) | Off unless you turn it on |
 
 Layers (who may import whom) always run. ArkRules, ArkRun, and ArkOrder change no
 inter-layer verdict when absent. Label leftovers **`[Layer]`** vs **`[ArkRules]`** vs
@@ -142,15 +150,13 @@ check: [4.3.0 — What ArkGate is / isn't](docs/releases/4.3.0.md#what-arkgate-i
 
 ## Why it exists
 
-AI coding agents generate code at unprecedented speeds. However, they tend to take the shortest path to solve a problem. If an agent needs data in a Domain layer, it might directly import a database adapter. Left unchecked, this creates spaghetti code and technical debt at light speed.
-
-Traditional linters catch these architectural violations in CI *after* the agent has finished its work, breaking the flow.
-
-ArkGate solves this by shifting the check to the exact moment of writing:
+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.
 
-1. **Fail fast at the write boundary.** Through IDE hooks and MCP, ArkGate intercepts the file write. If the agent writes a bad import, the write doesn't land. The agent gets immediate feedback and can self-correct before saving to disk.
-2. **The check is the single source of truth.** A simple `ark.config.json` defines your layers and allowed edges.
-3. **Honest reporting.** Green imports do not equal elegant design. ArkGate separates structural correctness from design smells, providing an improvement compass to guide leftover design work without blocking the PR.
+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”.
 
 ---
 
@@ -188,7 +194,9 @@ Details: [docs/use.md](docs/use.md).
 **Read the CI column:** for every host, the repository-wide hard guarantee is a **required**
 GitHub **status context** that runs the CLI — not “CI file present,” and not the CLI binary name alone.
 Codex hard write covers only a complete local `apply_patch`; Cursor covers only listed
-`preToolUse` ops. In both cases the project hook must be installed + trusted, while shell/direct
+`preToolUse` ops with `failClosed: true`. A Cursor hook without that flag is fail-open
+(if the checker cannot run, the write still lands). In both cases the project hook must be
+installed + trusted, while shell/direct
 filesystem writes, hosted or specialized opt-out paths, and human edits still rely on CI.
 
 This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run `arkgate-check --doctor` (or `ark-check --doctor`) for the evidence actually detected in the current repository.
@@ -251,7 +259,7 @@ npx arkgate-check --strict-merge   # CI / required status
 npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok,antigravity
 # optional: refresh shared home skills (Claude/Grok/Antigravity/Codex; never downgrades)
 # npx arkgate-check --install-agent-gates --skills-only --agent-homes --force
-# optional: same 13 skills via Agent Skills ecosystem (no new names)
+# optional: closed skill catalog via Agent Skills ecosystem (ARK_SKILL_NAMES)
 # npx skills add ./node_modules/arkgate/templates/agent-skills
 # optional ArkRun: poll the loopback inspector (ANSI TUI — not a gate)
 # npx ark-dashboard --url http://127.0.0.1:<port>/snapshot
@@ -313,9 +321,12 @@ Name the few choices (`xiKeys`: plan, cycle, tenancy — not seat counts). First
 freeze is `release()`. Later change is `proposeRelease` then `apply`. A generic
 `update` does not land.
 
-The billing gallery lives on GitHub, not in the npm tarball:
-[examples/arkorder-billing](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing).
-Compact starters leave it off. Details: [ArkOrder](docs/arkorder.md).
+Proof path (GitHub, not the npm tarball):
+[examples/arkorder-billing](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing)
+— first freeze is `release()`; later plan change is `proposeRelease` then `apply`.
+Gallery index:
+[examples/README.md](https://github.com/pedroknigge/arkgate/blob/main/examples/README.md).
+Compact starters leave the extra off. Details: [ArkOrder](docs/arkorder.md).
 
 ---
 
@@ -331,7 +342,7 @@ Compact starters leave it 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) |
-| Prepared (4.8.13; not published) | [CHANGELOG](CHANGELOG.md) |
+| Prepared (4.8.15; not published) | [CHANGELOG](CHANGELOG.md) |
 | Current published (4.8.11 on npm `latest`) | [docs/releases/4.8.11.md](docs/releases/4.8.11.md) · [CHANGELOG](CHANGELOG.md) |
 | Prior published (4.8.10) | [docs/releases/4.8.10.md](docs/releases/4.8.10.md) · [CHANGELOG](CHANGELOG.md) |
 | Prior published (4.8.9) | [docs/releases/4.8.9.md](docs/releases/4.8.9.md) · [CHANGELOG](CHANGELOG.md) |

package/SECURITY.md

@@ -28,9 +28,11 @@ a private security contact without including exploit details.
 ArkGate releases are GitHub-first:
 
 1. Changes land on GitHub and must pass CI plus the dedicated security workflow.
-2. A GitHub Release is created from a signed `vX.Y.Z` tag (`git tag -s`). The publish
-   workflow verifies the signature and fails closed for unsigned tags. The local override
-   exists only for explicit emergency use and is not enabled in CI.
+2. A GitHub Release is created from an **annotated** `vX.Y.Z` tag (`git tag -a` is
+   enough). The publish workflow checks that the tag matches `package.json` and is
+   annotated. Unsigned annotated tags are allowed. Signed tags still verify when
+   present. Set `ARK_REQUIRE_SIGNED_RELEASE_TAG=true` on the publish job only if
+   you want signed-only again.
 3. The manual `Publish npm` workflow verifies the tag, requires the GitHub Release to
    exist, reruns release checks, publishes npm with provenance, and uploads a SHA-256
    checksum for the npm tarball to the GitHub Release.

package/bin/ark-check-runtime.mjs

@@ -12,17 +12,13 @@ import {
   DEFAULT_RULES,
   applyFrameworkLayoutOverlays,
   arkCommand,
-  ADOPTION_PLAN_FILENAME,
-  buildArchitectureRecommendation,
   createElevenLayerConfig,
   enrichViolationWithFixClass,
   listPolicyPackIds,
   loadPolicyPackMeta,
-  writeAdoptionPlan,
   detectWorkspaces,
   detectTsPackageRoots,
   resolveIncludeRoots,
-  formatArchitectureRecommendationHuman,
   installDevHint,
   layerForFile,
 } from './ark-shared.mjs';
@@ -67,6 +63,7 @@ import {
   runCoverage,
   runPlan,
   runDoctor,
+  printAdrPresenceHint,
 } from './lib/doctor-plan.mjs';
 import { runRatchetCores } from './lib/core-ratchet.mjs';
 import {
@@ -77,6 +74,7 @@ import {
   writeBaseline,
   printViolation,
   printViolationBreakdown,
+  printWarning,
   CONCENTRATION_MIN_VIOLATIONS,
 } from './lib/violations.mjs';
 import {
@@ -102,6 +100,8 @@ import {
   UNGOVERNED_PROBE_CAP,
   collectGovernedFiles,
   countUngovernedSourceFiles,
+  governedFilesFromRelativePaths,
+  isGovernedSourcePath,
   normalize,
   walk,
 } from './lib/scan-files.mjs';
@@ -110,7 +110,7 @@ import { runArchitectureScan } from './lib/architecture-scan.mjs';
 import {
   ANALYSIS_COMPLETENESS,
   analysisIncompleteStatement,
-  emptyAnalysisRefusal,
+  emptyAnalysisRefusal, classifiedCountFromFiles,
 } from './lib/analysis-completeness.mjs';
 import { reportUnavailableAnalysis } from './lib/unavailable-analysis.mjs';
 import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
@@ -123,7 +123,6 @@ import {
   applyAgainstRatchet,
   bindTeamBaseRefs,
   contractSessionFrom,
-  filterChangedGovernedFiles,
   runTeamPreflight,
   ungovernedDumpMessage,
 } from './lib/team-parliament-io.mjs';
@@ -135,7 +134,7 @@ import {
   resolveEffectiveProjectRoot,
 } from './lib/project-root.mjs';
 import { demoteArkRuleTeethUnderClassificationFloor } from './lib/rules-under-contract.mjs';
-import { parseArgs, resolveDesignDeltaBaseRef } from './lib/check-args.mjs';
+import { localCheckEnvelope, parseArgs, resolveDesignDeltaBaseRef } from './lib/check-args.mjs';
 import { detectConfig, proposeForUncovered } from './lib/check-config-detect.mjs';
 import { runWatchMode } from './lib/check-watch.mjs';
 
@@ -1151,42 +1150,8 @@ async function main() {
   }
 
   if (args.recommend) {
-    try {
-      const recommendation = buildArchitectureRecommendation(args.root);
-      let planWritten;
-      if (args.writePlan) {
-        const result = writeAdoptionPlan(args.root, recommendation);
-        planWritten = result.path;
-      }
-      if (args.json) {
-        console.log(
-          JSON.stringify(
-            {
-              ...recommendation,
-              ...(planWritten
-                ? { adoptionPlanPath: path.relative(args.root, planWritten) || ADOPTION_PLAN_FILENAME }
-                : {}),
-            },
-            null,
-            2
-          )
-        );
-      } else {
-        console.log(formatArchitectureRecommendationHuman(recommendation));
-        if (planWritten) {
-          console.log('');
-          console.log(`Wrote ${path.relative(args.root, planWritten) || ADOPTION_PLAN_FILENAME}`);
-        }
-      }
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      if (args.json) {
-        console.log(JSON.stringify({ ok: false, error: message }, null, 2));
-      } else {
-        console.error(`ark-check --recommend failed: ${message}`);
-      }
-      process.exitCode = 2;
-    }
+    const { runRecommend } = await import('./lib/recommend-cli.mjs');
+    runRecommend(args);
     return;
   }
 
@@ -1207,9 +1172,11 @@ async function main() {
   let governedCache = null;
   const loadGovernedFiles = () => (governedCache ??= collectGovernedFiles(root, loadConfig()));
   const emptyAnalysisRefusalNow = () => {
-    const governedCount = loadGovernedFiles().length;
+    const governedFiles = loadGovernedFiles();
+    const governedCount = governedFiles.length;
     return emptyAnalysisRefusal({
       governedFileCount: governedCount,
+      classifiedFileCount: classifiedCountFromFiles(governedFiles, loadConfig().layers, layerForFile, root),
       // Probed only when nothing is governed, and never through the contract's own
       // exclude: the config under suspicion must not get to answer the question about
       // itself (`exclude: ["**"]` would otherwise read as greenfield and pass).
@@ -1347,7 +1314,7 @@ async function main() {
             (compactHost
               ? `AGENTS.md, compact host registration (${compactHost})`
               : REQUIRED_GATE_FILES.join(', '))
-        );
+        ); printAdrPresenceHint(args.root, (line) => console.log(line));
       }
       if (writeRequest?.host) {
         console.log(`Ark hard-write hook present for ${writeRequest.host}.`);
@@ -1382,7 +1349,7 @@ async function main() {
         JSON.stringify(
           {
             ok: preflight.halt.exitCode === 0,
-            ...(preflight.halt.cheap ? { cheap: true } : {}),
+            ...(preflight.halt.cheap ? { cheap: true } : {}), ...localCheckEnvelope(args, root),
             teamParliament: preflight.halt.teamParliament,
             ...(policyDelta ? { policyDelta } : {}),
           },
@@ -1405,8 +1372,7 @@ async function main() {
   }
   const manifest = readManifest(root, args.manifest);
   const rules = manifest?.architecture?.rules ?? config.rules;
-  const allGovernedFiles = loadGovernedFiles();
-  if (verdictPath) {
+  if (verdictPath && !args.changed && !isMutatingCliCommand(args)) {
     const refusal = emptyAnalysisRefusalNow();
     if (refusal) {
       reportEmptyAnalysis(refusal);
@@ -1414,10 +1380,9 @@ async function main() {
     }
   }
   if (args.failUngoverned && teamParliament?.changeSet?.productPaths?.length) {
-    const governedRel = new Set(
-      allGovernedFiles.map((abs) => normalize(path.relative(root, abs)))
+    const dumped = teamParliament.changeSet.productPaths.filter(
+      (rel) => !isGovernedSourcePath(root, rel, config)
     );
-    const dumped = teamParliament.changeSet.productPaths.filter((rel) => !governedRel.has(rel));
     if (dumped.length > 0) {
       const message = ungovernedDumpMessage(dumped);
       if (args.json) {
@@ -1430,8 +1395,8 @@ async function main() {
     }
   }
   const files = args.changed
-    ? filterChangedGovernedFiles(allGovernedFiles, root, changedPaths, normalize)
-    : allGovernedFiles;
+    ? governedFilesFromRelativePaths(root, changedPaths, config)
+    : loadGovernedFiles();
 
   // --coverage is a pure glob/report view (no TypeScript resolver), so serve it BEFORE the
   // TS import: the report must work — and exit 0 — even when typescript isn't installed.
@@ -1473,7 +1438,10 @@ async function main() {
     config,
     manifest,
     rules,
-    files,
+    // Full-tree callers already have the governed list. Passing it as `files`
+    // used to trigger the --changed scoped path (import-closure + a second
+    // resolveModuleName pass) on every doctor/check (#212). Empty = unbounded.
+    files: args.changed ? files : [],
     ts,
     args,
   });
@@ -1534,7 +1502,7 @@ async function main() {
       configWalkedUp: args.configWalkedUp === true,
       safety, designDelta,
       ts, parseHealth, completeness,
-      all: args.all === true,
+      all: args.all === true, requireGates: args.requireGates === true,
     });
     if (designDelta) process.exitCode = !designDelta.complete ? 2 : designDelta.valid ? 0 : 1; return;
   }
@@ -1946,7 +1914,7 @@ async function main() {
     });
     console.log(JSON.stringify({
       ...adapterResult,
-      ok,
+      ok, ...localCheckEnvelope(args, root),
       violations: activeViolations.map(enrichViolationWithFixClass),
       suppressedViolations: suppressed.length,
       staleBaselineKeys,
@@ -1966,7 +1934,7 @@ async function main() {
     }, null, 2));
   } else {
     for (const warning of warnings) {
-      console.error(`${color.yellow('warning')} ${warning.ruleId} ${warning.message}`);
+      printWarning(warning);
     }
     for (const violation of activeViolations) {
       printViolation(violation);