arkgate 4.8.8 → 4.8.10

package/CHANGELOG.md

@@ -3,6 +3,145 @@
 All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are documented here or
 in the immutable pre-2.0 archive linked below.
 
+## 4.8.10 — 2026-09-02
+
+**Patch** over **4.8.9**. Amarilla first-aggregate sensors. Incomplete analysis
+never looks green: an enforced sensor that cannot see its scope is not a pass.
+**Write. Check. Ship.** **No required config migration.** No `schemaVersion` bump.
+Does not close `K01` / `Z09`. No new skill names.
+
+**Status: prepared** (tree candidate; npm `latest` remains **4.8.9** until the
+signed-tag provenance workflow succeeds).
+
+### Added
+- `arkgate report` / `ark report` on the existing dual bins: draft an upstream GitHub issue for
+  `pedroknigge/arkgate` (`package.json` `bugs.url`), never the consumer repo. Default prints the
+  draft (arkgate version + last-check snippet). Create only with `--submit` and
+  `--i-confirm-submit` (or TTY `Type submit to send`). `--yes` does not submit. Missing or
+  unauthenticated `gh` prints the draft and the exact `gh issue create` command, then exits 2.
+  Not `ark-check --report` (HTML). Does not close `K01` / `Z09`. No new skill names.
+
+### Fixed
+- Structural-hint budget: when eligible governed files exceed `coverage.maxFiles`
+  (default `400`), emit `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 is truncated. No `arkrules.hintBudget` key.
+- `--update-baseline` GitHub rewrite touches only `ark-check` / `arkgate-check`
+  invocation lines (`run:` / package scripts). It does not append `--baseline` to
+  `concurrency.group` or job-id lines that merely name the check. Writes outside
+  the three law files are announced (`Synced --baseline into: …`).
+- DomainModel class sensors: method finder is paren-balanced, so a later broken
+  method is visible. Remaining truncation is reported (`shape analysed until
+  character N`), not silent green.
+- One shared invariant-word list (`ensureInvariants` / `raise` / `record` / `.push(`).
+  Assignment `=` is distinct from `===` / `!==` / `<=` / `>=`. `pendingEvents = []`
+  is idiomatic; events-array `.push(` counts as publish. Object literals and
+  multiline params are not public fields.
+- `ARKRULE_SCOPE_EMPTY` is not freezable, even with `--force`. It is a config
+  diagnostic, not code debt. No `allowEmptyScope` key.
+- `ARKRULE_STRUCTURE` freeze keys include the sensor id (and symbol when present).
+  A freeze for `orchestration-only` does not silence `thin-adapter` or
+  `writes-via-aggregate` on the same file. v1 empty-target keys remain exact-match
+  only.
+- Intent-prefix checks apply only at declared intent-reference sites (`publish` /
+  `subscribe` / `defineIntent` / `registerHandler`, `intent` / `onEvent` /
+  `reactsTo`, publish `metadata.source`). Not every string literal. No
+  `kernel.dtypePrefixes`. A kernel DType such as `Management.EvmInspection.Data`
+  does not trip `LAYER_INTENT_REFERENCE_VIOLATION`.
+- A5: `writes-via-aggregate` treats `@/lib/db` (and local `…/db`) as an IO import
+  without opening tsconfig. Write tokens require callee `db` / `tx` / `client` /
+  `prisma` / `drizzle`; `repo.update(` is not a write. Optional resolved-import
+  facts: PersistenceAdapters layer is a driver.
+- IO import hints match `postgres` and `drizzle-orm/postgres-js` (package
+  subpaths), in lockstep for ArkRules and ArkOrder. `require()` matches the same
+  packages.
+- React/UI `.set()` is not `ARKORDER_GENERIC_UPDATE`. Only `plane` /
+  `orderPlane` callees (or a file that constructs `createOrderPlane`) count as ξ
+  mutation. `Map` / `URLSearchParams` / `useState` setters stay silent.
+- `--sensors` success is not a validity verdict. Stdout names the contract-only
+  skip (`Contract + coverage-evidence only: no TypeScript, no analysis. Not a
+  validity verdict.`); `--json` stamps `notAVerdict` / `didNotRun` /
+  `partialMode=contract-only`. It does not print `Ark check passed`.
+
+### Changed
+- `coverage.maxFiles` schema description, configuration docs, and diagnostics name
+  that the same budget also bounds structural-hint preload for `orchestration-only`,
+  `thin-adapter`, and `writes-via-aggregate`.
+- Brownfield: law-then-product PR sequence when a rule’s folder does not exist yet
+  (advisory or placeholder path, then product, then promote). STRUCTURE key compat
+  for v1 empty-target rows is documented.
+- A10: baseline regenerate note lists
+  `ark-check --update-baseline --force --contract-session --author <steward>`.
+  Doctor concentration looks at `sensor` / `arkruleId`; orchestration-only
+  majority is code debt, not “Fixing the contract”. Short `--help`: `--sensors`
+  does not run analysis; `--help --all` lists `--update-baseline` / `--author`.
+  AO11 9-vs-7 is not a bug.
+- A11: `--changed` bounds file-local structural sensors and hint load to the
+  touched files. Import-edge, layer, and cycle sensors still see the full
+  governed graph. Optional process-local hint cache by content hash. Does not
+  claim 170s becomes seconds. No second analysis engine.
+
+## 4.8.9 — 2026-09-01
+
+**Patch** over **4.8.8**. Field diagnostic honesty: doctor default homedir, live
+`peerIsolation` walls are not dead rules, skippable CI is `ci-not-fail-closed`
+not `missing-gates`, blocked upgrade JSON carries `reasonCode` + `nextCommand`,
+content identity vs raw `afterHash`, cross-layer `peerIsolation` docs, and
+intent-reference checks share the import classifier. Amarilla ArkOrder:
+`appliesTo`, watchlist vs `maxXiKeys`, `restore`, default clock, `hashOf`,
+`.d.ts` honesty, packaged example URL, and ingest-payload honesty.
+**No required config migration.** No `ark.config.json` schema bump. Does not close `K01` / `Z09`.
+No new skill names.
+
+**Status: published** (on npm `latest`; see `docs/releases/4.8.9.md`).
+
+### Added
+- Optional `arkOrder.appliesTo` globs (same engine as layers). `managedLayers`
+  still required; empty or absent `appliesTo` keeps today's all-files-in-layer
+  emit; a Persistence write outside the globs stays silent.
+- `OrderPlane.restore(release)` installs a previously frozen `Release` (current
+  + version). Hash remains the identity. Not durable. Does not close `K01`.
+- Public `arkgate/order` exports `hashOf` (alias of `hashReleasePayload`) so a
+  stored `Release.hash` can be verified without calling `release()`.
+
+### Fixed
+- `--doctor` no longer throws when `CLAUDE_HOME` / `GROK_HOME` / `ANTIGRAVITY_HOME`
+  are unset (`skillsDirFor` now defaults `os.homedir()`).
+- `contract-dead-rule` skips a live `peerIsolation` wall (`allowed: false` on a
+  same-layer or cross-layer pair). A self-allow stays dead. The fix text never
+  tells an agent to delete that wall.
+- `--strict-merge` / `--require-gates` still fail skippable CI (`if:` other than
+  `true` / `always()`), but as `ci-not-fail-closed` (names the workflow file).
+  `missing-gates` remains only for files that are actually absent.
+- Blocked `ark upgrade --apply --json` includes `reasonCode: managed-consent-required`
+  and a digest-bound `nextCommand` already carrying `--accept-conflicts`. Apply stays
+  atomic.
+- `LAYER_INTENT_REFERENCE_VIOLATION` uses the same `peerIsolation` classifier as
+  imports (`fromPath` + `sharedRoots`). Shared-root files do not inherit the
+  slice-wall message. Cross-slice file imports still deny.
+- Default `createOrderPlane` clock is Kernel `Date.now()` (was `0` with no
+  warning). Domain stays clock-free. Tests that need determinism still inject.
+
+### Changed
+- Public managed-upgrade assets expose `beforeIdentity` / `afterIdentity`.
+  `afterHash` is the SHA-256 of the raw desired bytes; `state: current` is content
+  identity, so stamp-only `arkVersion` drift can be current with unequal raw hashes.
+- Docs: a slice wall on a cross-layer edge is a `peerIsolation` rule on that
+  `from`/`to` pair (`allowed: false`). Domain files without a slice fail-closed
+  unless listed in `sharedRoots`. No new engine mode, key, or skill.
+- `maxXiKeys` caps one `release()` / `assertXiKeyCap` only. `xiKeys` is a
+  repo-wide watchlist; eight named keys with `maxXiKeys` 7 is valid config.
+  Sensor `arkorder-too-many-params` fires on `release()` `keyCount`, not on
+  config list length.
+- Public `dist/order` `.d.ts` no longer says declarations-only / no runtime.
+- Packaged docs point the billing gallery at the GitHub tree
+  (`https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing`).
+  The folder is not in the npm tarball; `examples/` is not added to
+  `package.json` `files`.
+- Ingest payload-dependent escalation stays deliberate: `classifyIngest` uses
+  `kind`; `ConstraintPack` forbids user predicates. "Second week failing a
+  goal" is a domain/projector kind, not a pack function.
+
 ## 4.8.8 — 2026-09-01
 
 **Patch** over **4.8.7**. ArkRun gains an opt-in terminal dashboard and bounded,
@@ -10,8 +149,7 @@ payload-free inspector monitors. ArkOrder and first-contact docs gain honesty co
 **No required config migration.** No `ark.config.json` schema bump. Does not close
 `K01` / `Z09`.
 
-**Status: prepared** (tree candidate; npm `latest` remains **4.8.7** until the
-signed-tag provenance workflow succeeds).
+**Status: published** (see `docs/releases/4.8.8.md`).
 
 ### Added
 - Dual **`ark-dashboard` / `arkgate-dashboard`** bins render the loopback ArkRun
@@ -40,7 +178,7 @@ show it when present. Caption-only edits do not change `policyHash`.
 **No required config migration.** No `schemaVersion` bump. Does not close `K01` / `Z09`.
 No new skill names.
 
-**Status: published** (on npm `latest`; see `docs/releases/4.8.7.md`).
+**Status: published** (see `docs/releases/4.8.7.md`).
 
 ### Added
 - Public name for existing `layers[].description`. Example:

package/README.md

@@ -37,7 +37,7 @@ Works with Cursor, Claude, Codex, and Grok.
 
 </div>
 
-> **ArkGate 4.8.8** is prepared on this tree; npm `latest` remains **4.8.7**.
+> **ArkGate 4.8.10** is prepared on this tree; npm `latest` remains **4.8.9**.
 > 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 +45,7 @@ Works with Cursor, Claude, Codex, and Grok.
 > (`arkgate/order`) stops the agent rewriting the few slow product decisions as CRUD;
 > later pattern change is `proposeRelease` then `apply`.
 > `@arkgate/runtime` is deprecated.
-> [4.8.8 prepared](docs/releases/4.8.8.md) · [4.8.7 published](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.10 prepared](docs/releases/4.8.10.md) · [4.8.9 published](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)
 
 ---
 
@@ -321,8 +321,10 @@ PATCHes those keys through Prisma is named. Same npm package.
 In-memory. Not durable. Does not replace ArkRun.
 **ArkOrder freezes the pattern through a valve. ArkRun is how the residual travels.**
 
-Copy [examples/arkorder-billing/](examples/arkorder-billing/) and rename the
-three keys. Compact starters leave it off. Details:
+The billing gallery (`plan` / `cycle` / `tenancy`) lives on GitHub, not in the
+npm tarball:
+[examples/arkorder-billing](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing).
+Rename the three keys. Compact starters leave it off. Details:
 [ArkOrder](docs/arkorder.md) · [configuration](docs/configuration.md) ·
 [package surface](docs/package-surface.md).
 
@@ -340,8 +342,9 @@ three keys. Compact starters leave it off. Details:
 | 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.8; not published) | [docs/releases/4.8.8.md](docs/releases/4.8.8.md) · [CHANGELOG](CHANGELOG.md) |
-| Current published (4.8.7 on npm `latest`) | [docs/releases/4.8.7.md](docs/releases/4.8.7.md) · [CHANGELOG](CHANGELOG.md) |
+| Prepared (4.8.10; not published) | [docs/releases/4.8.10.md](docs/releases/4.8.10.md) · [CHANGELOG](CHANGELOG.md) |
+| Current published (4.8.9 on npm `latest`) | [docs/releases/4.8.9.md](docs/releases/4.8.9.md) · [CHANGELOG](CHANGELOG.md) |
+| Prior published (4.8.7) | [docs/releases/4.8.7.md](docs/releases/4.8.7.md) · [CHANGELOG](CHANGELOG.md) |
 | Prior published (4.8.6) | [docs/releases/4.8.6.md](docs/releases/4.8.6.md) |
 | Prior published (4.8.5) | [docs/releases/4.8.5.md](docs/releases/4.8.5.md) |
 | Prior published (4.8.4) | [docs/releases/4.8.4.md](docs/releases/4.8.4.md) |

package/bin/ark-check-runtime.mjs

@@ -47,6 +47,7 @@ import {
   REQUIRED_GATE_FILES,
   detectWritePathCapabilities,
 } from './lib/agent-gates.mjs';
+import { ciNotFailClosed } from './lib/gate-files.mjs';
 import { syncBaselineIntoCheckSurfaces } from './lib/field-install.mjs';
 import {
   detectEnforcement,
@@ -95,7 +96,7 @@ import {
   writeArkRulesTemplates,
 } from './lib/presets.mjs';
 import { loadArkConfigContract, parseArkConfigJson } from './lib/config-contract.mjs';
-import { checkUsage, checkUsageAll } from './lib/first-run-help.mjs';
+import { checkUsage, checkUsageAll, withSensorsPartialModeHonesty } from './lib/first-run-help.mjs';
 import { createAdapterResult } from './lib/adapter-contract.mjs';
 import {
   UNGOVERNED_PROBE_CAP,
@@ -1139,7 +1140,7 @@ async function main() {
 
   if (args.sensors) {
     const { runSensors } = await import('./lib/sensor-promote-cli.mjs');
-    await runSensors(args, readConfig);
+    await withSensorsPartialModeHonesty(args, () => runSensors(args, readConfig));
     return;
   }
 
@@ -1307,6 +1308,27 @@ async function main() {
       process.exitCode = 1;
       return;
     }
+    if (args.requireGates) {
+      const ci = ciNotFailClosed(args.root);
+      if (ci) {
+        const payload = {
+          ok: false,
+          error: ci.error,
+          message: ci.message,
+          workflowFile: ci.workflowFile,
+          nextAction: ci.nextAction,
+          ...(writeRequest?.host ? { writeHost: writeRequest.host } : {}),
+        };
+        if (args.json) {
+          console.log(JSON.stringify(payload, null, 2));
+        } else {
+          console.error(`${color.red('\u2716')} ${ci.error} ${ci.message}`);
+          console.error(`Next: ${ci.nextAction}`);
+        }
+        process.exitCode = 1;
+        return;
+      }
+    }
     // Gates present. This is a precondition, not a standalone report: stay quiet
     // in --json mode so the architecture check below owns the single JSON output.
     // When --require-gates is the only intent (no config/architecture run needed),

package/bin/ark-layer-match.mjs

@@ -362,15 +362,27 @@ export function crossSliceEdgeAllowed(allowedCrossSlice, fromSlice, toSlice) {
  * Fail-closed stays fail-closed: absent evidence denies. What changed in 4.8.4
  * is what counts as evidence — a declared shared root, or a declared directed
  * cross-slice edge, is the repo telling us its design, so it is no longer
- * "unclassifiable". Order: no paths → no slice folders → a side that is neither
- * in a slice nor declared shared → same slice → declared cross edge → deny.
+ * "unclassifiable". Order: no fromPath → no slice folders → intent (no toPath):
+ * shared-root allow / slice fail-closed → a side that is neither in a slice nor
+ * declared shared → same slice → declared cross edge → deny.
+ *
+ * Intent/event names are not files. Callers pass fromPath only and must not
+ * invent a toPath (that would mis-slice). A declared shared root is classified
+ * the same way as on import edges.
  */
 export function peerIsolationDecision(input) {
-    if (!input.fromPath || !input.toPath)
+    if (!input.fromPath)
         return { denied: true, reason: 'missing-path' };
     if (input.folderCount <= 0)
         return { denied: true, reason: 'no-slice-folders' };
     const fromClassified = Boolean(input.fromSlice) || input.fromShared === true;
+    if (!input.toPath) {
+        if (!fromClassified)
+            return { denied: true, reason: 'unclassifiable-path' };
+        if (!input.fromSlice)
+            return { denied: false };
+        return { denied: true, reason: 'missing-path' };
+    }
     const toClassified = Boolean(input.toSlice) || input.toShared === true;
     if (!fromClassified || !toClassified)
         return { denied: true, reason: 'unclassifiable-path' };
@@ -387,8 +399,9 @@ export function peerIsolationDecision(input) {
 /**
  * Boolean face of {@link peerIsolationDecision}, kept for parity consumers.
  *
- * Fail-closed: missing path, no classifiable folders, or unclassifiable either
- * side → deny. Same-slice → allow (return false). Cross-slice → deny unless the
+ * Fail-closed: missing fromPath, no classifiable folders, or unclassifiable
+ * either side → deny. Intent refs (no toPath) allow only a declared shared
+ * root. Same-slice → allow (return false). Cross-slice → deny unless the
  * rule declared that directed edge.
  */
 export function peerIsolationMustDeny(input) {
@@ -426,9 +439,11 @@ export function peerIsolationDenyExplanation(reason, context) {
  *   Same-layer is always allowed (historical short-circuit).
  * - `peerIsolation: true` + `allowed: false`: deny only when importer and importee
  *   resolve to **different** slice ids (same or cross layer). Same-slice → allow.
- *   Missing paths, no slice folders, or unclassifiable slices → **fail-closed**
- *   (deny): isolation is configured, so insufficient evidence must not silently
- *   allow a possible cross-slice edge.
+ *   File imports pass fromPath + toPath. Intent references pass fromPath only.
+ *   A declared shared root is classified (no denial). Missing fromPath, no slice
+ *   folders, or unclassifiable slices → **fail-closed** (deny): isolation is
+ *   configured, so insufficient evidence must not silently allow a possible
+ *   cross-slice edge.
  */
 export function findDeniedEdgeRule(rules, from, to, options) {
     return findDeniedEdgeDecision(rules, from, to, options)?.rule;
@@ -448,8 +463,8 @@ export function findDeniedEdgeDecision(rules, from, to, options) {
             const fromPath = options?.fromPath;
             const toPath = options?.toPath;
             const folders = resolveSliceFolders(rule, from, options?.layers);
-            const fromSlice = fromPath && toPath ? sliceIdForPath(fromPath, folders) : undefined;
-            const toSlice = fromPath && toPath ? sliceIdForPath(toPath, folders) : undefined;
+            const fromSlice = fromPath ? sliceIdForPath(fromPath, folders) : undefined;
+            const toSlice = toPath ? sliceIdForPath(toPath, folders) : undefined;
             const decision = peerIsolationDecision({
                 fromPath,
                 toPath,

package/bin/ark.mjs

@@ -36,6 +36,7 @@ import {
 import { runStatusCommand } from './lib/status-command.mjs';
 import { runAgentProjectionCommand } from './lib/agent-projection-command.mjs';
 import { setupUsage, setupUsageAll, upgradeUsage } from './lib/first-run-help.mjs';
+import { runUpstreamReportCommand } from './lib/upstream-report.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const arkCheck = path.join(here, 'ark-check.mjs');
@@ -45,20 +46,20 @@ Usage: arkgate dashboard [--url <snapshot-url>] [--interval <ms>]
 Polls an ArkRun inspector; it does not start the kernel.`;
 
 function withDashboardHelp(text, detailed) {
+  const extra = detailed
+    ? '  arkgate dashboard [--url <snapshot-url>] [--interval <ms>]\n  arkgate report  [--root <project>] [--json] [--title <text>] [--finding <ref>] [--submit] [--i-confirm-submit]\n'
+    : '';
+  const extraDesc = detailed
+    ? '  dashboard  ANSI observability TUI (spawns ark-dashboard).\n  report     Draft an upstream GitHub issue for pedroknigge/arkgate. Create needs --submit plus confirm. --yes does not submit.\n'
+    : '';
   if (detailed) {
     return text
-      .replace(
-        '  arkgate agents-md [--root',
-        '  arkgate dashboard [--url <snapshot-url>] [--interval <ms>]\n  arkgate agents-md [--root'
-      )
-      .replace(
-        '  agents-md Version-matched',
-        '  dashboard  ANSI observability TUI against a running ArkRun inspector (spawns ark-dashboard).\n  agents-md Version-matched'
-      );
+      .replace('  arkgate agents-md [--root', `${extra}  arkgate agents-md [--root`)
+      .replace('  agents-md Version-matched', `${extraDesc}  agents-md Version-matched`);
   }
   return text.replace(
     '  arkgate-check --doctor     status — one next step\n',
-    '  arkgate-check --doctor     status — one next step\n  arkgate dashboard         observability TUI (inspector)\n'
+    '  arkgate-check --doctor     status — one next step\n  arkgate dashboard         observability TUI (inspector)\n  arkgate report            draft an upstream GitHub issue\n'
   );
 }
 
@@ -181,7 +182,7 @@ function parseArgs(argv) {
     else if (!arg.startsWith('-') && args.command === undefined) {
       args.command = arg;
       // Dashboard owns its flags (--url/--interval); pass the rest through untouched.
-      if (arg === 'dashboard') {
+      if (arg === 'dashboard' || arg === 'report') {
         args.passthrough = argv.slice(i + 1);
         break;
       }
@@ -946,6 +947,13 @@ async function main() {
     });
   }
 
+  if (args.command === 'report') {
+    return runUpstreamReportCommand({
+      root: args.root, json: args.json, yes: args.yes,
+      arkgateVersion: cliVersion(), argv: args.passthrough,
+    });
+  }
+
   if (args.command === 'agents-md' || args.command === 'agent-projection') {
     return runAgentProjectionCommand({
       root: args.root,

package/bin/lib/agent-homes.mjs

@@ -108,7 +108,7 @@ function usesDefaultHome(spec, env, homeDir) {
 
 function skillsDirFor(host, env = process.env) {
   const spec = HOSTS[host];
-  return path.join(resolveHomeDir(spec, env), 'skills');
+  return path.join(resolveHomeDir(spec, env, os.homedir()), 'skills');
 }
 
 function readHomeCatalogFloor(skillsDir) {