arkgate 4.8.9 → 4.8.11

package/docs/README.md

@@ -71,9 +71,9 @@ 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: [releases/4.8.9.md](releases/4.8.9.md) (`arkgate@4.8.9`; not published).
-Current published: [releases/4.8.8.md](releases/4.8.8.md) (`arkgate@4.8.8` on npm `latest`; does not close `K01`).
-Prior published: [releases/4.8.7.md](releases/4.8.7.md) (`arkgate@4.8.7`).
+Prepared: [releases/4.8.11.md](releases/4.8.11.md) (`arkgate@4.8.11`; not published).
+Current published: [releases/4.8.10.md](releases/4.8.10.md) (`arkgate@4.8.10` on npm `latest`; does not close `K01`).
+Prior published: [releases/4.8.9.md](releases/4.8.9.md) (`arkgate@4.8.9`).
 Prior: [releases/4.8.6.md](releases/4.8.6.md) · [releases/4.8.5.md](releases/4.8.5.md) · [releases/4.8.4.md](releases/4.8.4.md) · [releases/4.8.3.md](releases/4.8.3.md) · [releases/4.8.2.md](releases/4.8.2.md) · [releases/4.8.1.md](releases/4.8.1.md) · [4.8.0](releases/4.8.0.md) · [4.7.6](releases/4.7.6.md) · [4.7.5](releases/4.7.5.md) · [4.7.4](releases/4.7.4.md) · [4.7.3](releases/4.7.3.md) · [4.7.2](releases/4.7.2.md) · [4.7.1](releases/4.7.1.md) · [4.7.0](releases/4.7.0.md) · [4.6.7](releases/4.6.7.md) · [4.6.6](releases/4.6.6.md) · [4.6.5](releases/4.6.5.md) · [4.6.4](releases/4.6.4.md) · [4.6.3](releases/4.6.3.md) · [4.6.2](releases/4.6.2.md) · [4.6.1](releases/4.6.1.md) · [4.6.0](releases/4.6.0.md).
 Older notes: [releases/](releases/). Config: [configuration.md](configuration.md).
 

package/docs/agent-guide.md

@@ -93,11 +93,26 @@ Default loop for each agent session (product language — no inventing residual)
    `unavailable`, run `ark-check --doctor` (and `--json` for the full 15-lens map) before treating
    residual as complete. When mode is `full`, status residual ids are a subset of doctor residual
    for the same facts.
+5. **Report ArkGate defects to upstream (human confirms first)** — if you find a bug, a false
+   green, a false red, a missing doc, or improvable behavior **in ArkGate itself** (the `arkgate`
+   package — not leftover design in the consumer app), run **`arkgate report` / `ark report`**
+   (existing dual bins — not a new skill). Default prints a draft GitHub issue for **upstream**
+   `pedroknigge/arkgate` (`package.json` `bugs.url`) with the installed arkgate version and an
+   optional last-check snippet. **Ask the human to confirm send.** Create only with `--submit`
+   **and** `--i-confirm-submit` (after they said yes) or a TTY `Type submit to send`. `--yes`
+   does not submit. One finding per invocation (`--finding <ref>`); otherwise one bundled field
+   report (`--title` is editable). If `gh` is missing or not logged in, the CLI prints the draft
+   plus the exact `gh issue create --repo pedroknigge/arkgate` command and exits 2. Never auto-file.
+   Never file ArkGate defects on the consumer product repo. This is not `ark-check --report` (HTML).
 
 ```bash
 npx ark status --json --expected-root /abs/project/root
 # mode !== full → full residual map:
 npx ark-check --doctor --json
+# draft an upstream issue (nothing created yet):
+npx ark report
+# after the human says yes — one finding, upstream only:
+npx ark report --submit --i-confirm-submit
 ```
 
 `--doctor --json` is a stable envelope (4.6.5+): `{ "schemaVersion": "1.0", "envelope": "doctor", "ok": boolean, "doctor": { … } }`.
@@ -1096,7 +1111,7 @@ edges are not denied by that rule.
 - **`allowedCrossSlice`** (4.8.4): `[{ "from": "features/checkout", "to": "features/catalog" }]` — one directed slice→slice edge the repo declares on purpose. The reverse still denies.
 - **The denial names its reason:** `cross-slice edge a → b` (a fact about the code) vs `unclassifiable path (…)`, `no slice folders`, `no path evidence` (facts about the evidence ArkGate had).
 - Promoting a genuinely shared slice to its own layer remains the recommended model; the two declarations exist so ArkGate can enforce a repo that deliberately chose otherwise.
-- Enforced by `ark-check`, `arkgate/eslint`, and `ark-mcp` (path-aware edges and path-less intent refs share the same SoT).
+- Enforced by `ark-check`, `arkgate/eslint`, and `ark-mcp` (path-aware edges and path-less intent refs at declared event/saga/publish-metadata sites share the same SoT).
 - Fixes are **judgment** (not mechanical-safe).
 
 Agents can generate a config from the project's actual directory layout instead of inventing layer mappings:
@@ -1147,6 +1162,15 @@ Example config:
 plus intent/publish evidence. It uses the nearest `tsconfig.json` unless `--tsconfig` is set;
 importless type references are out.
 
+Intent-prefix checks (`LAYER_INTENT_REFERENCE_VIOLATION` on the candidate, write-hook
+`LAYER_REFERENCE_VIOLATION` / `UNKNOWN_INTENT`) apply only at declared intent-reference sites:
+`publish` / `subscribe` / `defineIntent` / `registerHandler` arguments, `intent` / `onEvent` /
+`reactsTo` properties, and publish `metadata.source` (or the 2nd/3rd-arg `source` object). A
+string that merely matches a layer prefix — including a kernel DType name such as
+`Management.EvmInspection.Data` — is not an intent reference. `looksLikeArkIntent` still
+classifies names; it is not a scan of every quoted string. There is no `kernel.dtypePrefixes`
+exemption list. Real event and saga string refs still fail closed.
+
 Each run parses the full candidate and ignores retired `.cache/ark-check.json`; `--no-cache` is a
 no-op. Z07 owns the identity-keyed snapshot after exact cold/warm parity.
 

package/docs/ai-gates.md

@@ -894,3 +894,11 @@ Adopting Ark on an existing codebase with violations? Freeze them once and ratch
 npx ark-check --update-baseline   # writes .ark-baseline.json — commit it
 npx ark-check --baseline          # only NEW violations fail
 ```
+
+`--update-baseline` also patches existing check **invocations** so CI keeps using the
+new freeze file: `package.json` scripts and GitHub workflow `run:` lines that already
+call `ark-check` / `arkgate-check` via `npx`, `pnpm`, `yarn`, `npm`, or `node`. Those
+writes are outside the three law files (`ark.config.json`, `arkrules/`,
+`.ark-baseline.json`) and are announced (`Synced --baseline into: …`). The matcher
+does **not** append `--baseline` to YAML that only *names* the check — a
+`concurrency.group` such as `ark-check-${{ github.ref }}`, or a job id `ark-check:`.

package/docs/brownfield-adoption.md

@@ -135,6 +135,36 @@ If Ark still refuses (a single edge dominates), the contract is still wrong —
 step 3; don't `--force` past it. From now `ark-check --baseline` fails only on NEW
 violations — the ratchet only moves toward zero.
 
+`ARKRULE_SCOPE_EMPTY` is a **config diagnostic**, not code debt. It is **not freezable**
+(even with `--force`). There is no `allowEmptyScope` key: an enforced rule whose
+`appliesTo` matches zero governed files is incomplete analysis and must not look green.
+
+### Law then product (when a rule needs a folder that does not exist yet)
+
+`mixed-law-and-product` still requires law files (`ark.config.json`, `arkrules/`,
+`.ark-baseline.json`) to travel without product. When the product folder is not there
+yet, do **not** freeze the empty-scope finding. Sequence:
+
+1. **Law PR (advisory or placeholder):** declare the ArkRule as `advisory`, *or* point
+   `appliesTo` at a tracked placeholder path that already exists. Empty enforced scope
+   fails the gate and cannot be baselined.
+2. **Product PR:** add the folder and the code so `appliesTo` matches governed files.
+3. **Law PR (promote):** raise the rule to `enforced` (hash-bound policy acknowledgement
+   when required). The ratchet then protects the now-visible scope.
+
+### STRUCTURE freeze keys include the sensor
+
+New `ARKRULE_STRUCTURE` keys are `ARKRULE_STRUCTURE|<file>|<layer>||<sensor>` (and
+`<sensor>:<symbol>` when a class/method symbol is known). A freeze for
+`orchestration-only` on a file must not silence `thin-adapter` or `writes-via-aggregate`
+on the same file.
+
+**v1 empty-target keys** (`ARKRULE_STRUCTURE|<file>|<layer>||`) still load as frozen
+residual, but they are **exact-match only**. They do not prefix-match every later sensor
+on that file — hidden new debt must not look green. After upgrade they go stale; re-freeze
+in a law PR (`--update-baseline --force --contract-session --author <steward>` as
+applicable) so new keys carry the sensor. Do not treat stale v1 rows as a wildcard mute.
+
 ## 5. Burn down, in order
 
 `summary.edges` is the burn-down order. Prefer `ark-check --plan`: it tags each step

package/docs/configuration.md

@@ -90,7 +90,13 @@ Top-level fields:
   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.
-  Unknown keys fail closed. When the budget is hit, `INVARIANT_UNCOVERED` reports the numbers
+  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
+  governed files exceed that budget, the loader emits `ARKRULE_HINT_BUDGET_EXHAUSTED` with
+  exact hinted/governed counts and per-sensor reviewed N/M of scope; `--strict-config` fails
+  if an enforced hint sensor cannot see its scope. `--doctor` names this coupling.
+  When the coverage budget is hit, `INVARIANT_UNCOVERED` reports the numbers
   (files loaded, tests retained, files discarded at the cap) and names `coverage.maxFiles` as
   the knob that raises it — coverage never claims "never had tests" because of our own cap.
   `maxFiles` is clamped to a hard ceiling of 20000 (the config validator has no
@@ -447,6 +453,13 @@ Write-gate ApplyPatch denies a batch that mixes law files with product source. H
 never hit PreToolUse are unchanged. Local `pnpm` gates should call `--changed --base`, not
 only full-tree `--strict-merge`.
 
+`--changed` honors the touched-file list for **file-local** ArkRules structure sensors
+(class shape, orchestration-only, thin-adapter, writes-via-aggregate) and for
+structural-hint preload. Import-edge, layer, and cycle sensors still evaluate the full
+governed graph. That is a bound on the existing scan, not a second analysis engine, and
+it does not turn a full-tree run into a seconds-long one. A `--changed` pass is not a
+full-tree structural verdict.
+
 MCP clients can call `ark_policy_delta` with the previous `baseConfig`, an optional candidate
 contract (the current project contract is the default), and the same optional acknowledgement.
 It invokes the public classifier directly, is read-only, and marks a blocking result as an MCP

package/docs/diagnostics.md

@@ -43,6 +43,7 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 | [`ARKRULE_STRUCTURE`](#ARKRULE_STRUCTURE) | arkrules | ArkRule structure sensor failed |
 | [`ARKRULE_INVARIANT`](#ARKRULE_INVARIANT) | arkrules | ArkRule invariant failed |
 | [`ARKRULE_SCOPE_EMPTY`](#ARKRULE_SCOPE_EMPTY) | arkrules | ArkRule appliesTo matched zero files |
+| [`ARKRULE_HINT_BUDGET_EXHAUSTED`](#ARKRULE_HINT_BUDGET_EXHAUSTED) | arkrules | Structural-hint budget exhausted |
 | [`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 |
 | [`ARKRUN_MISSING_ROOT`](#ARKRUN_MISSING_ROOT) | arkrun | No kernel factory in composition roots |
@@ -279,6 +280,15 @@ Link form for agents: `docs/diagnostics.md#RULE_ID` (exact-case HTML anchors bel
 - **Why:** An ArkRule’s appliesTo globs matched no governed files — the rule cannot observe what it claims to protect.
 - **Fix:** Fix appliesTo globs so they match governed files, or remove the rule. Enforced empty scope fails; advisory empty scope warns.
 
+<a id="ARKRULE_HINT_BUDGET_EXHAUSTED"></a>
+
+### `ARKRULE_HINT_BUDGET_EXHAUSTED`
+
+**Structural-hint budget exhausted**
+
+- **Why:** `orchestration-only`, `thin-adapter`, and `writes-via-aggregate` only evaluate files the hint loader preloaded. When eligible governed files exceed that budget (`coverage.maxFiles`, default `400` — there is no `arkrules.hintBudget`), those sensors never saw the rest of their scope. Enforced + unreviewed is not green. The finding names exact hinted/governed counts and per-sensor reviewed N/M of scope.
+- **Fix:** Raise `coverage.maxFiles` in ark.config.json (this cap also bounds structural-hint preload; `--doctor` names the coupling) so hinted/governed counts match, then re-run with `--strict-config`. An enforced hint sensor that cannot see its scope fails strict.
+
 <a id="INVARIANT_UNCOVERED"></a>
 
 ### `INVARIANT_UNCOVERED`

package/docs/package-surface.md

@@ -37,7 +37,8 @@ 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**) 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. `ark status --json` is the unified status snapshot. `ark agents-md` is the version-matched agent projection (non-authoritative). **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. `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. |
 | **Improvement compass (4.4; status honesty 4.5)** | `ark-check --doctor --json` → `doctor.improvementCompass`; human doctor section **Improvement compass (not a score)**; HTML report `data-advisory="improvementCompass"`. **`ark status --json` / MCP `ark_status`** project a thin `improvementCompass` residual map with explicit honesty **`mode`**: `full` \| `subset` \| `unavailable` (always `notAScore: true`). When `mode` is `full`, status residual lens **ids** are a **subset of** doctor residual for the same facts (report snapshot stores the thin slice after `--report`). Incomplete or missing session facts → `subset` / `unavailable` + `reasonCode` / `reason` — **never invent green residual**. Residual never flips `valid` / strict-merge / `goal.met`. When status mode ≠ full, run doctor for full 15-lens detail. | Additive schema `1.0`. Closed **15** lens ids (`soc`, `cohesion`, `coupling`, `srp`, `dip`, `ocp`, `encapsulation`, `modularity`, `scalability`, `resilience`, `security`, `maintainability`, `testability`, `domain`, `stack`) with status `ok` \| `residual` \| `not-instrumented` \| `out-of-scope`, evidence refs, optional `nextAction`, capped `topResidual`, always **`notAScore: true`**. Projection from existing smells / walls / cohesion / ArkRules / design-weak only — **never** a gate input. Out-of-scope locked for scalability, resilience, and app security (no residual invent from missing SAST/APM). Root API: `buildImprovementCompass` / `IMPROVEMENT_LENS_IDS`; status: `projectStatusImprovementCompass` / `STATUS_COMPASS_MODES`. |
@@ -265,8 +266,9 @@ production deployment would need to satisfy; it is not a readiness certification
 ## Release notes (maintainers)
 
 Ship notes for a version live under [releases/](https://github.com/pedroknigge/arkgate/tree/main/docs/releases)
-(current tree candidate: [4.8.9.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.9.md), prepared and not published;
-current published: [4.8.8.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.8.md);
+(current published: [4.8.10.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.10.md);
+prior published: [4.8.9.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.9.md);
+prior published: [4.8.8.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.8.md);
 prior published: [4.8.7.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.7.md);
 prior published: [4.8.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.6.md);
 prior published: [4.8.5.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.5.md);

package/docs/use.md

@@ -163,12 +163,23 @@ Short loop so agents do not invent residual or re-run doctor every message:
    **`unavailable`** (or compass facts are missing), run `npx ark-check --doctor` (add `--json` for
    the full 15-lens map) before treating residual as complete. When mode is **`full`**, status
    residual ids are a safe subset of doctor residual for the same facts.
+5. **If ArkGate itself is wrong** — run `npx arkgate report` (alias `ark report`). Default prints
+   a draft GitHub issue for **upstream** `pedroknigge/arkgate` (`package.json` `bugs.url`) with
+   the arkgate version and last-check snippet. **Ask the human to confirm send.** Create only
+   with `--submit` and `--i-confirm-submit` (or TTY `Type submit to send`). `--yes` does not
+   submit. If `gh` is missing, the command prints the draft plus `gh issue create --repo
+   pedroknigge/arkgate …` and exits 2. Never auto-file. Never file ArkGate defects on the
+   consumer product repo. Not `arkgate-check --report` (HTML).
 
 ```bash
 npx ark status --json --expected-root /abs/project/root
 # when mode is not full:
 npx ark-check --doctor
 npx ark-check --doctor --json   # doctor.improvementCompass
+# draft an upstream issue (nothing created yet):
+npx ark report
+# after the human says yes — one finding, upstream only:
+npx ark report --submit --i-confirm-submit
 ```
 
 Details: [agent-guide — Session recipe](agent-guide.md#session-recipe-agent-turn) ·

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.8.9",
+  "version": "4.8.11",
   "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",
@@ -188,7 +188,8 @@
     "qs": "6.15.3",
     "vite": "6.4.3",
     "postcss": "8.5.23",
-    "fast-uri": "3.1.5",
+    "fast-uri": "3.1.7",
+    "browserslist": "4.28.8",
     "nanoid": "3.3.18",
     "brace-expansion@2": "2.1.4",
     "brace-expansion@5": "5.0.9",

package/schemas/ark.config.schema.json

@@ -837,7 +837,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; 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.",
       "properties": {
         "testGlobs": {
           "type": "array",
@@ -850,7 +850,8 @@
         },
         "maxFiles": {
           "type": "integer",
-          "minimum": 1
+          "minimum": 1,
+          "description": "Evidence file budget (default 400) and structural-hint preload cap for orchestration-only, thin-adapter, and writes-via-aggregate. Raise this when hinted/governed counts show truncated sensors. There is no separate arkrules.hintBudget."
         },
         "coverageRoots": {
           "type": "array",

package/server.json

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

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

@@ -19,6 +19,7 @@ description: Map import rules and leftover design. No apply. CLI is a sensor; yo
 - Doctor #1: if ENFORCE + empty plan A and gates are already installed → **Shape** (`/ark-explore` then `/ark-autopilot`). Do not say install-agent-gates.
 - 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.
 
 ## Autonomy contract
 
@@ -27,7 +28,24 @@ incomplete. **Do not write** config or product code (that is `/ark-adopt` / `/ar
 **CLI budget:** one doctor / coverage; then open ≥12 files across ≥4 dirs; then the map.
 
 **Still never:** weaken the config; invent `mechanical-safe` kinds; claim healthy because
-plan A is empty while leftover design work remains.
+plan A is empty while leftover design work remains; auto-file GitHub issues; file ArkGate
+defects on the consumer product repo; skip the human confirm step.
+
+## Report ArkGate defects (ask first)
+
+This skill maps **this** tree. If recon shows a bug, false green, false red, missing doc, or
+improvable behavior **in ArkGate itself** (the `arkgate` package — not leftover design in the
+consumer app):
+
+1. Draft one GitHub issue for **upstream** (`pedroknigge/arkgate`, or `package.json`
+   `repository.url` of the installed `arkgate` package).
+2. **Ask the human in the loop to confirm send.** Do not create the issue until they say yes.
+3. If confirmed, `gh issue create` with the logged-in account. One finding per issue. Include
+   repro commands, version, and measured evidence.
+4. Never auto-file, batch-spam, or skip confirm. Never file ArkGate defects on the consumer
+   product repo.
+
+Reporting is not applying product code. Stay map-only on this tree.
 
 Use when you need a decision-grade map or the **Primary post-green door**; hand off to
 `/ark-autopilot` to apply. Day-to-day place + gate work does not require this skill.
@@ -431,6 +449,9 @@ Optional: **Diff vs naive sensor-only read** (what reading the tree changed).
 - Mode respected: no multi-week roadmap in recon mode; dual-plan seed capped at 3–5 B bets.
 - Clear handoff: `/ark-adopt` | `/ark-autopilot` | `/ark-place` | CLI | `stop`.
 - No gate weakening; no false ENFORCE claim; no README echo as primary content.
+- If you found a bug / false green / false red / missing doc / improvable behavior in the
+  **ArkGate package**, you drafted one upstream issue, asked the human to confirm, and did not
+  `gh issue create` until they said yes. Never filed it on the consumer repo.
 
 ## Completion contract (skill incomplete if missing)
 

package/templates/skills/ark-explore.md

@@ -19,6 +19,7 @@ description: Map import rules and leftover design. No apply. CLI is a sensor; yo
 - Doctor #1: if ENFORCE + empty plan A and gates are already installed → **Shape** (`/ark-explore` then `/ark-autopilot`). Do not say install-agent-gates.
 - 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.
 
 ## Autonomy contract
 
@@ -27,7 +28,24 @@ incomplete. **Do not write** config or product code (that is `/ark-adopt` / `/ar
 **CLI budget:** one doctor / coverage; then open ≥12 files across ≥4 dirs; then the map.
 
 **Still never:** weaken the config; invent `mechanical-safe` kinds; claim healthy because
-plan A is empty while leftover design work remains.
+plan A is empty while leftover design work remains; auto-file GitHub issues; file ArkGate
+defects on the consumer product repo; skip the human confirm step.
+
+## Report ArkGate defects (ask first)
+
+This skill maps **this** tree. If recon shows a bug, false green, false red, missing doc, or
+improvable behavior **in ArkGate itself** (the `arkgate` package — not leftover design in the
+consumer app):
+
+1. Draft one GitHub issue for **upstream** (`pedroknigge/arkgate`, or `package.json`
+   `repository.url` of the installed `arkgate` package).
+2. **Ask the human in the loop to confirm send.** Do not create the issue until they say yes.
+3. If confirmed, `gh issue create` with the logged-in account. One finding per issue. Include
+   repro commands, version, and measured evidence.
+4. Never auto-file, batch-spam, or skip confirm. Never file ArkGate defects on the consumer
+   product repo.
+
+Reporting is not applying product code. Stay map-only on this tree.
 
 Use when you need a decision-grade map or the **Primary post-green door**; hand off to
 `/ark-autopilot` to apply. Day-to-day place + gate work does not require this skill.
@@ -431,6 +449,9 @@ Optional: **Diff vs naive sensor-only read** (what reading the tree changed).
 - Mode respected: no multi-week roadmap in recon mode; dual-plan seed capped at 3–5 B bets.
 - Clear handoff: `/ark-adopt` | `/ark-autopilot` | `/ark-place` | CLI | `stop`.
 - No gate weakening; no false ENFORCE claim; no README echo as primary content.
+- If you found a bug / false green / false red / missing doc / improvable behavior in the
+  **ArkGate package**, you drafted one upstream issue, asked the human to confirm, and did not
+  `gh issue create` until they said yes. Never filed it on the consumer repo.
 
 ## Completion contract (skill incomplete if missing)