arkgate 4.8.15 → 4.8.16

package/dist/{types-TBiv0WHL.d.ts → types-BSzRy2X1.d.ts}

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

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

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

package/docs/README.md

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

package/docs/agent-guide.md

@@ -120,6 +120,8 @@ npx ark report --submit --i-confirm-submit
 
 `--doctor --json` is a stable envelope (4.6.5+): `{ "schemaVersion": "1.0", "envelope": "doctor", "ok": boolean, "doctor": { … } }`.
 Payload lives only under `doctor`. Do not parse sibling root keys as the doctor object.
+A green or Healthy line names a file, config key, or test so a stranger can
+check it in about a minute. Uncited green is not honest — treat it as unfinished.
 
 Doctor also writes `.ark/ci-merge-boundary.json` (hook configured-not-fired, per-host writePath,
 CI present-but-not-required, GitHub Free cannot require). Read that file — do not grep `node_modules`.

package/docs/configuration.md

@@ -89,7 +89,14 @@ Top-level fields:
 - **`coverage`** (optional) — invariant-coverage scan controls: `testGlobs` (globs that decide
   which files count as tests, replacing the built-in `*.test.*` / `tests/` name heuristic),
   `maxFiles` (evidence file budget, default `400`) and `coverageRoots` (path prefixes where the
-  project declares its runner actually executes tests). Absence is silent and changes no verdict.
+  project declares its runner actually executes tests). Absence is silent unless the tree is
+  **adopted** (required CI or `.ark/adoption-stance.json` advisory-only) **and** the catalog
+  has domain invariants that want test evidence (`coverage.test` is not `false`) —
+  then a missing or empty tests path fails closed
+  (`INVARIANT_TESTS_PATH_MISSING`). Either `testGlobs` or `coverageRoots` satisfies the path.
+  When any catalogued invariant is **enforced**, `coverage.coverageRoots` is required
+  (`INVARIANT_COVERAGE_ROOTS_MISSING`) — `testGlobs` alone is not enough. Silent when no
+  invariant is enforced.
   Unknown keys fail closed. **`maxFiles` also bounds structural-hint preload** for
   `orchestration-only`, `thin-adapter`, and `writes-via-aggregate` (the hint loader reuses
   coverage contents when present). There is no separate `arkrules.hintBudget`. When eligible
@@ -117,8 +124,9 @@ Top-level fields:
   the invariant just as well as one that runs. Declaring `coverageRoots` gives ArkGate a second
   declaration to compare the first against: when the only covering test falls outside them, it
   reports `INVARIANT_COVERAGE_OUTSIDE_ROOTS` (advisory) and refuses to promote that invariant to
-  `enforced`. Declaring nothing keeps the old silence — without a declaration there is nothing to
-  compare, and ArkGate makes no claim about where tests run.
+  `enforced`. Declaring nothing stays silent unless any invariant is already enforced — then
+  missing roots fail closed (`INVARIANT_COVERAGE_ROOTS_MISSING`), because otherwise coverage can
+  certify a test the project never declared a runner root for.
 - **`arkRules`** (optional, schema `1.1+`) — map of layer name → project-relative path to an
   ArkRules file (e.g. `"DomainModel": "arkrules/DomainModel.json"`). Keys must match a declared
   layer. Missing/invalid referenced files **fail closed**.

package/docs/develop.md

@@ -37,9 +37,11 @@ ArkGate solves this by shifting the check to the exact moment of writing. By int
 ```bash
 npm install -D arkgate typescript
 npx arkgate start --apply
-npx arkgate-check --doctor
+npx --package=arkgate arkgate-check --doctor
 ```
 
+`arkgate-check` is a command in the `arkgate` package. After a local install, `npx arkgate-check --doctor` also works.
+
 Make the import-rules check a **required** merge **status context** (GitHub/GitLab/etc.). The CLI
 command is `arkgate-check --strict-merge` / `ark-check --strict-merge` — the hard boundary is
 requiring that job’s status, not merely adding a workflow file:

package/docs/diagnostics.md

@@ -47,6 +47,8 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 | [`INVARIANT_CATALOG_EMPTY`](#INVARIANT_CATALOG_EMPTY) | arkrules | Domain invariant catalog is empty |
 | [`INVARIANT_UNCOVERED`](#INVARIANT_UNCOVERED) | arkrules | Invariant without coverage evidence |
 | [`INVARIANT_COVERAGE_OUTSIDE_ROOTS`](#INVARIANT_COVERAGE_OUTSIDE_ROOTS) | arkrules | Covering test outside the declared coverage roots |
+| [`INVARIANT_COVERAGE_ROOTS_MISSING`](#INVARIANT_COVERAGE_ROOTS_MISSING) | arkrules | Coverage roots missing while an invariant is enforced |
+| [`INVARIANT_TESTS_PATH_MISSING`](#INVARIANT_TESTS_PATH_MISSING) | arkrules | Domain-invariant tests path missing under adopted |
 | [`ARKRUN_MISSING_ROOT`](#ARKRUN_MISSING_ROOT) | arkrun | No kernel factory in composition roots |
 | [`ARKRUN_KERNEL_IN_DOMAIN`](#ARKRUN_KERNEL_IN_DOMAIN) | arkrun | Domain-role layer imports the kernel |
 | [`ARKRUN_DIRECT_NEW`](#ARKRUN_DIRECT_NEW) | arkrun | Managed type constructed with new |
@@ -318,7 +320,29 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 - **Why:** The only test naming this invariant sits outside `coverage.coverageRoots` — the places the project declares its runner executes. ArkGate matches declared text and never executes tests, so it cannot tell whether that file is ever run: coverage there is a test that *exists*, not a test that *runs*.
 - **Fix:** Move the test under a declared coverage root, or add its root to `coverage.coverageRoots` in ark.config.json. Advisory: it never fails strict, but promotion to enforced refuses on it.
 
-Declaring nothing is silent — without `coverage.coverageRoots` there is no second declaration to compare against, and ArkGate makes no claim about where tests run.
+Declaring nothing is silent unless any catalogued invariant is enforced — then missing roots fail closed (`INVARIANT_COVERAGE_ROOTS_MISSING`). Without `coverage.coverageRoots` there is no second declaration to compare against, and ArkGate makes no claim about where tests run.
+
+<a id="INVARIANT_COVERAGE_ROOTS_MISSING"></a>
+
+### `INVARIANT_COVERAGE_ROOTS_MISSING`
+
+**Coverage roots missing while an invariant is enforced**
+
+- **Why:** A catalogued domain invariant is enforced, but `ark.config.json` does not name `coverage.coverageRoots` — the folders where the project says its test runner actually goes. Without that declaration, `INVARIANT_COVERAGE_OUTSIDE_ROOTS` cannot fire and coverage can certify a test no runner runs.
+- **Fix:** Add `coverage.coverageRoots` in `ark.config.json` pointing at the folder the test runner uses, then re-run. `testGlobs` alone is not enough. Fail-closed until that path is present. Not freezable.
+
+No enforced invariant, or roots already declared, stays silent. This is not a new config key. Promotion to enforced also refuses without roots.
+
+<a id="INVARIANT_TESTS_PATH_MISSING"></a>
+
+### `INVARIANT_TESTS_PATH_MISSING`
+
+**Domain-invariant tests path missing under adopted**
+
+- **Why:** The project is adopted (required CI or explicit advisory) and has domain invariants that want test evidence, but `ark.config.json` does not name where those tests live. Green coverage without a real tests path is an empty checkbox.
+- **Fix:** Add `coverage.testGlobs` or `coverage.coverageRoots` in `ark.config.json` pointing at a real tests folder, then re-run. Adopted mode fails closed until that path is present. Not freezable.
+
+Not adopted, no catalogued invariants, or every invariant sets `coverage.test: false`, stays silent. This is not a new config key.
 
 ## ArkRun (opt-in extra)
 

package/docs/package-surface.md

@@ -39,7 +39,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 
 | Surface | How you use it | Stability notes |
 |---------|----------------|-----------------|
-| **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`); optional ArkRun **`ark-dashboard`** / **`arkgate-dashboard`** | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend, **status**, **agents-md**, **report**) are stable within a major. Additive fields OK; removals/renames are major. From 4.2, `--require-gates` implies strict config and verifies semantic Ark AGENTS, project-rooted MCP/compact Codex registration, and fail-closed CI rather than file presence alone. Soft ADR presence: when that demand (or doctor `required-merge`) is on and `docs/adr/` / `docs/decisions/` is missing, doctor JSON may add `adrPresence` and human copy points at a short decision note — never a fail, omitted when the demand is off. Soft states/transitions: when a conventional domain doc is already in play and the map is missing or heading-only, doctor JSON may add `statesTransitions` and human copy points at a short table (or one link) — never a fail, omitted when that doc is absent. Narrow status/transition catalog: when Domain-role code already names a closed status/state vocabulary and that map is still thin, doctor JSON may add `statusTransitionCatalog` with those names — never a fail, omitted when Domain has no such vocabulary, the domain doc is absent, or the map is already present. Soft no-Domain / UI-logic residual: when a Domain-role layer is declared but empty and presentation holds the tree (or `domain-logic-in-ui` is already present), doctor JSON may add `noDomainFrontend` and human copy points at one Domain file — never a fail, omitted when there is no frontend, Domain already has files, or the UI bag is too thin. `ark status --json` is the unified status snapshot. `ark agents-md` is the version-matched agent projection (non-authoritative). **`arkgate report` / `ark report`** drafts an upstream GitHub issue for `pedroknigge/arkgate` (`package.json` `bugs.url`) — never the consumer repo. **Dashboard bins** poll an ArkRun inspector snapshot (ANSI + interval polling; `--url` / `--interval`); they are not a gate verdict. The main CLI also accepts `ark dashboard` / `arkgate dashboard` as a passthrough to those bins. |
+| **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`); optional ArkRun **`ark-dashboard`** / **`arkgate-dashboard`** | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend, **status**, **agents-md**, **report**) are stable within a major. Additive fields OK; removals/renames are major. From 4.2, `--require-gates` implies strict config and verifies semantic Ark AGENTS, project-rooted MCP/compact Codex registration, and fail-closed CI rather than file presence alone. Soft ADR presence: when that demand (or doctor `required-merge`) is on and `docs/adr/` / `docs/decisions/` is missing, doctor JSON may add `adrPresence` and human copy points at a short decision note — never a fail, omitted when the demand is off. Soft states/transitions: when a conventional domain doc is already in play and the map is missing or heading-only, doctor JSON may add `statesTransitions` and human copy points at a short table (or one link) — never a fail, omitted when that doc is absent. Narrow status/transition catalog: when Domain-role code already names a closed status/state vocabulary and that map is still thin, doctor JSON may add `statusTransitionCatalog` with those names — never a fail, omitted when Domain has no such vocabulary, the domain doc is absent, or the map is already present. Soft no-Domain / UI-logic residual: when a Domain-role layer is declared but empty and presentation holds the tree (or `domain-logic-in-ui` is already present), doctor JSON may add `noDomainFrontend` and human copy points at one Domain file — never a fail, omitted when there is no frontend, Domain already has files, or the UI bag is too thin. Soft prototype-shortcut residual: when a Persistence-role layer is declared and SQLite or a JSON-file store lives outside it, or Domain / an auth tag is declared and admin / god-mode literals sit outside that house, doctor JSON may add `prototypeShortcuts` and human copy points at one Persistence adapter or Domain policy file — never a fail, omitted when those houses are absent, the shortcut is already in the right house, or there are no such markers. `ark status --json` is the unified status snapshot. `ark agents-md` is the version-matched agent projection (non-authoritative). **`arkgate report` / `ark report`** drafts an upstream GitHub issue for `pedroknigge/arkgate` (`package.json` `bugs.url`) — never the consumer repo. **Dashboard bins** poll an ArkRun inspector snapshot (ANSI + interval polling; `--url` / `--interval`); they are not a gate verdict. The main CLI also accepts `ark dashboard` / `arkgate dashboard` as a passthrough to those bins. |
 | **Upstream report CLI (4.8.10)** | `arkgate report` / `ark report` on the existing dual bins (no new bin, no new skill) | Default prints a draft for **upstream** `pedroknigge/arkgate` (`package.json` `bugs.url`) with the arkgate version and optional last-check snippet. Create only with `--submit` **and** `--i-confirm-submit` (after HITL) or TTY `Type submit to send`. `--yes` does not submit. Missing/unauthenticated `gh`: print the draft plus the exact `gh issue create --repo pedroknigge/arkgate` command, exit 2. Never files against the consumer repo. Not `ark-check --report` (HTML architecture report). |
 | **Host write boundaries** | Generated trusted PreToolUse/preToolUse hooks + `ark-mcp --hook`; inspect with doctor/status | Hard is always operation-scoped and runtime-evidenced. From 4.6.3, Codex CLI and local ChatGPT Desktop/App Server can hard-block a complete `apply_patch` sent as `tool_input.command`; `.codex/hooks.json` on disk remains unverified until a fresh covered invocation. Hosted tools, specialized hook opt-outs, shell/direct writes, incomplete reconstruction, and humans rely on required CI. Repair envelopes may emit, but Codex reinjection is not guaranteed. |
 | **Programmatic gate API** | `import { analyzeProject, loadContract, createAICodeGate, ... } from 'arkgate'` | The root export is the static gate/config/analysis contract listed below. It intentionally contains no runtime-kernel implementation. |

package/docs/use.md

@@ -27,10 +27,12 @@ For **anyone** shipping TypeScript with an AI coding agent.
 npm install -D arkgate typescript
 npx arkgate start                 # preview what will change
 npx arkgate start --apply         # install compact config + host router + CI; merge write-path gates into existing AGENTS.md / .mcp.json
-npx arkgate-check --doctor        # status — one next step
-npx arkgate-check --doctor --all  # full details
+npx --package=arkgate arkgate-check --doctor        # status — one next step
+npx --package=arkgate arkgate-check --doctor --all  # full details
 ```
 
+`arkgate-check` is a command in the `arkgate` package, not its own npm package. After a local install, `npx arkgate-check --doctor` also works.
+
 `start --apply` 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
@@ -40,7 +42,7 @@ Then keep working with your agent. Stuck? Run `--doctor` and do action **#1**. C
 
 | Stuck on… | Do this |
 |-----------|---------|
-| Unsure | `npx arkgate-check --doctor` |
+| Unsure | `npx --package=arkgate arkgate-check --doctor` |
 | Agent broke architecture | Fix the edge doctor names (or re-run check) |
 | Code is green but still a mess | Leftover design work — see below |
 | New ArkGate version | Follow doctor / upgrade guidance |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.8.15",
+  "version": "4.8.16",
   "description": "When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.",
   "type": "module",
   "main": "./dist/index.cjs",

package/schemas/ark.config.schema.json

@@ -858,7 +858,7 @@
     "coverage": {
       "type": "object",
       "additionalProperties": false,
-      "description": "Invariant coverage scan controls. testGlobs replaces the built-in test-name heuristic; maxFiles raises or lowers the evidence file budget and also bounds structural-hint preload for orchestration-only, thin-adapter, and writes-via-aggregate (default 400; there is no arkrules.hintBudget); coverageRoots declares where the project runs its tests, so a covering test found outside them is reported instead of silently certifying an invariant.",
+      "description": "Invariant coverage scan controls. testGlobs replaces the built-in test-name heuristic; maxFiles raises or lowers the evidence file budget and also bounds structural-hint preload for orchestration-only, thin-adapter, and writes-via-aggregate (default 400; there is no arkrules.hintBudget); coverageRoots declares where the project runs its tests, so a covering test found outside them is reported instead of silently certifying an invariant. When any invariant is enforced, missing coverageRoots fails closed.",
       "properties": {
         "testGlobs": {
           "type": "array",

package/server.json

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

package/templates/agent-skills/README.md

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

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

@@ -48,6 +48,21 @@ has honest houses. Skills never enforce — CLI / hooks / CI do.
   delete it to “clean” empty layers. Next is one Domain file (`/ark-place`), not
   a weaker contract. Soft. Silent when there is no frontend or Domain already
   has files. No `/ark-domain`.
+- When doctor JSON has `prototypeShortcuts`, keep the Persistence / Domain
+  house — do not delete it to “clean” empty layers. Next is one Persistence
+  adapter or Domain policy file (`/ark-place`), not a weaker contract. Soft.
+  Silent when those houses are absent or the shortcut is already in the right
+  house. No `/ark-prototype`.
+- When the tree is adopted and doctor JSON has `invariantTestsPath` (or the
+  check names `INVARIANT_TESTS_PATH_MISSING`), write `coverage.testGlobs` or
+  `coverage.coverageRoots` to a real tests folder. Fail-closed until that path
+  exists. Silent when not adopted, the catalog is empty, or every invariant
+  sets coverage.test false. No new skill.
+- When any invariant is enforced and doctor JSON has `invariantCoverageRoots`
+  (or the check names `INVARIANT_COVERAGE_ROOTS_MISSING`), write
+  `coverage.coverageRoots` to the folder the test runner uses. Fail-closed
+  until that path exists. `coverage.testGlobs` alone is not enough. Silent
+  when no invariant is enforced. No new skill.
 - CLI-first: if `arkgate-check` already resolved the root, do not wait on MCP.
 - Do not add `arkRun` or `arkOrder` unless the user wants that extra. When they do, write
   **advisory** extra in this turn (`arkRun` schema `1.2+`; `arkOrder` schema `1.3+`).

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

@@ -18,6 +18,9 @@ imports, one small change at a time. Skills never enforce — CLI / hooks / CI d
 2. Fix import-rule debt; if leftover design remains, apply **one** small refactor.
    When doctor JSON has `noDomainFrontend`, that refactor is one pure rule into
    Domain — not another UI helper. Soft. Silent when Domain already has files.
+   When doctor JSON has `prototypeShortcuts`, that refactor is one file-store
+   move into Persistence, or one admin literal behind Domain / an auth tag.
+   Soft. Silent when those houses are absent or the shortcut is already home.
 3. Re-run doctor. Never weaken `ark.config.json`.
 
 **This is the apply door.** Invoking it **is** the approval. Run `arkgate-check --doctor` for the next step.
@@ -143,7 +146,9 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 - After explore/doctor: if inventory has high-confidence candidates **or** user wants domain rules, include **[ArkRules] plan A/B**:
   - A: mechanical-safe remains inter-layer only; structure/invariant fixes are **judgment**.
   - B: one pilot = one rule (declare in `arkrules/<Layer>.json` → implement → test title/symbol → re-doctor).
-- Never promote advisory→enforced without coverage evidence (`canPromoteInvariant` / policy-delta).
+- Never promote advisory→enforced without coverage evidence and declared
+  `coverage.coverageRoots` (`canPromoteInvariant` / policy-delta). Missing
+  roots refuse promotion — otherwise OUTSIDE_ROOTS stays silent.
 - End report must list what was **layer-edge** work vs **intra-layer rule** work.
 
 ### Autopilot + ArkRun

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

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

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

@@ -24,7 +24,8 @@ Name 1–3 **residual** lenses in plain language before skill-shopping. Always `
 **What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.
 
 **Anti false-done:** empty plan A + residual lenses / design-weak → **Incomplete? yes**. Green edges alone
-are not “architecture finished.”
+are not “architecture finished.” A doctor green / Healthy line must name a
+file, config key, or test; uncited green is unfinished.
 
 **AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
 new files; place before write (`/ark-place` / prepare-write).

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

@@ -34,6 +34,25 @@ one bounded decision needs 2–3 enforceable options.
   rules. Next: one Domain file (`/ark-place`) then one small refactor
   (`/ark-autopilot`). Soft. Silent when there is no frontend or Domain already
   has files. No `/ark-domain`. Do not invent a Domain house.
+- When doctor JSON has `prototypeShortcuts`, SQLite / a JSON-file store is
+  standing in for Persistence, or admin / god-mode literals sit outside Domain
+  (or an auth tag). Next: one Persistence adapter or Domain policy file
+  (`/ark-place`) then one small refactor (`/ark-autopilot`). Soft. Silent when
+  those houses are absent, the shortcut is already in the right house, or there
+  are no such markers. No `/ark-prototype`. Do not invent a Persistence house.
+- When the tree is adopted and doctor JSON has `invariantTestsPath` (or the
+  check names `INVARIANT_TESTS_PATH_MISSING`), the next step is
+  `coverage.testGlobs` or `coverage.coverageRoots` on a real tests folder.
+  Fail-closed. Silent when not adopted, the catalog is empty, or every
+  invariant sets coverage.test false. Handoff
+  `/ark-adopt` to write the path. No new skill.
+- When any invariant is enforced and doctor JSON has `invariantCoverageRoots`
+  (or the check names `INVARIANT_COVERAGE_ROOTS_MISSING`), the next step is
+  `coverage.coverageRoots` on the folder the test runner uses. Fail-closed.
+  `testGlobs` alone is not enough. Silent when no invariant is enforced.
+  Handoff `/ark-adopt` to write the roots. No new skill.
+- A doctor green / Healthy line must name a file, config key, or test.
+  Uncited green is a lie — treat it as unfinished. No `/ark-cite`.
 - Distinguish **missing** skills vs **stale** catalog. Installed ≠ stale.
 - Hook green is not tree green (scripted edits bypass PreToolUse).
 - Bug / false green / false red / missing doc / improvable behavior **in ArkGate itself** → draft one upstream GitHub issue (`pedroknigge/arkgate` or the installed package `repository.url`), **ask the human to confirm send**, then `gh issue create`. Never auto-file. Never file ArkGate defects on the consumer product repo.

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

@@ -29,6 +29,10 @@ right house. Skills never enforce — CLI / hooks / CI do.
 - When doctor JSON has `noDomainFrontend`, the new file is a Domain rule — not
   another UI helper. Soft. Silent when Domain already has files or there is no
   frontend. No `/ark-domain`.
+- When doctor JSON has `prototypeShortcuts`, the new file is a Persistence
+  adapter or a Domain / auth-tag policy — not another SQLite / JSON-file store
+  or admin literal in the page. Soft. Silent when those houses are absent or
+  the shortcut is already in the right house. No `/ark-prototype`.
 - When the matched layer has `layers[].description`, print that caption next to the
   layer name and globs. Omit when absent — do not invent a caption or `/ark-describe`.
 - When the matched layer has `layers[].trustBoundary`, print `trust: <tag>` next

package/templates/skills/ark-adopt.md

@@ -48,6 +48,21 @@ has honest houses. Skills never enforce — CLI / hooks / CI do.
   delete it to “clean” empty layers. Next is one Domain file (`/ark-place`), not
   a weaker contract. Soft. Silent when there is no frontend or Domain already
   has files. No `/ark-domain`.
+- When doctor JSON has `prototypeShortcuts`, keep the Persistence / Domain
+  house — do not delete it to “clean” empty layers. Next is one Persistence
+  adapter or Domain policy file (`/ark-place`), not a weaker contract. Soft.
+  Silent when those houses are absent or the shortcut is already in the right
+  house. No `/ark-prototype`.
+- When the tree is adopted and doctor JSON has `invariantTestsPath` (or the
+  check names `INVARIANT_TESTS_PATH_MISSING`), write `coverage.testGlobs` or
+  `coverage.coverageRoots` to a real tests folder. Fail-closed until that path
+  exists. Silent when not adopted, the catalog is empty, or every invariant
+  sets coverage.test false. No new skill.
+- When any invariant is enforced and doctor JSON has `invariantCoverageRoots`
+  (or the check names `INVARIANT_COVERAGE_ROOTS_MISSING`), write
+  `coverage.coverageRoots` to the folder the test runner uses. Fail-closed
+  until that path exists. `coverage.testGlobs` alone is not enough. Silent
+  when no invariant is enforced. No new skill.
 - CLI-first: if `arkgate-check` already resolved the root, do not wait on MCP.
 - Do not add `arkRun` or `arkOrder` unless the user wants that extra. When they do, write
   **advisory** extra in this turn (`arkRun` schema `1.2+`; `arkOrder` schema `1.3+`).

package/templates/skills/ark-autopilot.md

@@ -18,6 +18,9 @@ imports, one small change at a time. Skills never enforce — CLI / hooks / CI d
 2. Fix import-rule debt; if leftover design remains, apply **one** small refactor.
    When doctor JSON has `noDomainFrontend`, that refactor is one pure rule into
    Domain — not another UI helper. Soft. Silent when Domain already has files.
+   When doctor JSON has `prototypeShortcuts`, that refactor is one file-store
+   move into Persistence, or one admin literal behind Domain / an auth tag.
+   Soft. Silent when those houses are absent or the shortcut is already home.
 3. Re-run doctor. Never weaken `ark.config.json`.
 
 **This is the apply door.** Invoking it **is** the approval. Run `arkgate-check --doctor` for the next step.
@@ -143,7 +146,9 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 - After explore/doctor: if inventory has high-confidence candidates **or** user wants domain rules, include **[ArkRules] plan A/B**:
   - A: mechanical-safe remains inter-layer only; structure/invariant fixes are **judgment**.
   - B: one pilot = one rule (declare in `arkrules/<Layer>.json` → implement → test title/symbol → re-doctor).
-- Never promote advisory→enforced without coverage evidence (`canPromoteInvariant` / policy-delta).
+- Never promote advisory→enforced without coverage evidence and declared
+  `coverage.coverageRoots` (`canPromoteInvariant` / policy-delta). Missing
+  roots refuse promotion — otherwise OUTSIDE_ROOTS stays silent.
 - End report must list what was **layer-edge** work vs **intra-layer rule** work.
 
 ### Autopilot + ArkRun

package/templates/skills/ark-coverage.md

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

package/templates/skills/ark-explain.md

@@ -24,7 +24,8 @@ Name 1–3 **residual** lenses in plain language before skill-shopping. Always `
 **What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.
 
 **Anti false-done:** empty plan A + residual lenses / design-weak → **Incomplete? yes**. Green edges alone
-are not “architecture finished.”
+are not “architecture finished.” A doctor green / Healthy line must name a
+file, config key, or test; uncited green is unfinished.
 
 **AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
 new files; place before write (`/ark-place` / prepare-write).

package/templates/skills/ark-explore.md

@@ -34,6 +34,25 @@ one bounded decision needs 2–3 enforceable options.
   rules. Next: one Domain file (`/ark-place`) then one small refactor
   (`/ark-autopilot`). Soft. Silent when there is no frontend or Domain already
   has files. No `/ark-domain`. Do not invent a Domain house.
+- When doctor JSON has `prototypeShortcuts`, SQLite / a JSON-file store is
+  standing in for Persistence, or admin / god-mode literals sit outside Domain
+  (or an auth tag). Next: one Persistence adapter or Domain policy file
+  (`/ark-place`) then one small refactor (`/ark-autopilot`). Soft. Silent when
+  those houses are absent, the shortcut is already in the right house, or there
+  are no such markers. No `/ark-prototype`. Do not invent a Persistence house.
+- When the tree is adopted and doctor JSON has `invariantTestsPath` (or the
+  check names `INVARIANT_TESTS_PATH_MISSING`), the next step is
+  `coverage.testGlobs` or `coverage.coverageRoots` on a real tests folder.
+  Fail-closed. Silent when not adopted, the catalog is empty, or every
+  invariant sets coverage.test false. Handoff
+  `/ark-adopt` to write the path. No new skill.
+- When any invariant is enforced and doctor JSON has `invariantCoverageRoots`
+  (or the check names `INVARIANT_COVERAGE_ROOTS_MISSING`), the next step is
+  `coverage.coverageRoots` on the folder the test runner uses. Fail-closed.
+  `testGlobs` alone is not enough. Silent when no invariant is enforced.
+  Handoff `/ark-adopt` to write the roots. No new skill.
+- A doctor green / Healthy line must name a file, config key, or test.
+  Uncited green is a lie — treat it as unfinished. No `/ark-cite`.
 - Distinguish **missing** skills vs **stale** catalog. Installed ≠ stale.
 - Hook green is not tree green (scripted edits bypass PreToolUse).
 - Bug / false green / false red / missing doc / improvable behavior **in ArkGate itself** → draft one upstream GitHub issue (`pedroknigge/arkgate` or the installed package `repository.url`), **ask the human to confirm send**, then `gh issue create`. Never auto-file. Never file ArkGate defects on the consumer product repo.

package/templates/skills/ark-place.md

@@ -29,6 +29,10 @@ right house. Skills never enforce — CLI / hooks / CI do.
 - When doctor JSON has `noDomainFrontend`, the new file is a Domain rule — not
   another UI helper. Soft. Silent when Domain already has files or there is no
   frontend. No `/ark-domain`.
+- When doctor JSON has `prototypeShortcuts`, the new file is a Persistence
+  adapter or a Domain / auth-tag policy — not another SQLite / JSON-file store
+  or admin literal in the page. Soft. Silent when those houses are absent or
+  the shortcut is already in the right house. No `/ark-prototype`.
 - When the matched layer has `layers[].description`, print that caption next to the
   layer name and globs. Omit when absent — do not invent a caption or `/ark-describe`.
 - When the matched layer has `layers[].trustBoundary`, print `trust: <tag>` next