arkgate 4.8.4 → 4.8.6

package/CHANGELOG.md

@@ -3,9 +3,76 @@
 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.6 — 2026-08-31
+
+**Patch** over **4.8.5**. Phase **LV** — ArkOrder valved loop. First `release()`
+freezes ξ; later pattern change is `proposeRelease` then `apply`. σ identity is
+not ξ identity. ingest returns a closed residual. Capacity is data. ArkRun
+carries the decision tape. **No required config migration.** Does not close
+`K01` / `Z09`. No `/ark-order` skill. Do not npm-publish from this item until
+the maintainer tag.
+
+**Status: prepared** (tree ready; npm `latest` remains **4.8.5** until publish).
+
+### Added
+- **`apply(ProposeResult)`** on `createOrderPlane`. Unvalved second freeze of a
+  different ξ fails `ARKORDER_UNVALVED_RELEASE` at runtime (not a lexical sensor).
+- **`xiHash` / `sigmaHash` / `refreshSigma`** — saldo refresh does not mint a pattern.
+- **Ingest residual** `absorb | escalate_up | hold` bound to `xiHash` + event
+  identity. Closed `reasonCode`: `not-in-pattern` | `stale-sigma` | `pack` |
+  `capacity`. `proposed_patch` only on `escalate_up`. `IngestEscalate.target` remains.
+- **Capacity pack as data** (`kind` / `sigmaKey` / `payloadKey` / `op`). No user
+  predicates. Over-cap is residual, not a homemade kind.
+- **ArkRun decision tape** on the information package (`{ xiHash, event, residual }`).
+  Component snapshot API unchanged. `shadow` / `compare` / `replay` in-process.
+- **`ReleaseStore` port** with in-memory default. Optional catalog digest keyed by
+  `catalogReleaseId`. Not durable. Not K01.
+- Thin gallery bridge: absorb may `send`; `escalate_up` human may `raises`.
+
+### Changed
+- Public sentence: **ArkOrder freezes the pattern through a valve. ArkRun is how
+  the residual travels.** Skills `/ark-adopt` `/ark-place` `/ark-autopilot` deepen.
+  Doctor / status remain `notAScore`.
+
+## 4.8.5 — 2026-08-31
+
+**Patch** over **4.8.4**. Phase **XP** (ArkOrder × ArkRun) plus Antigravity skill
+refresh. ArkOrder is a **library plus sensors, not a service** — that sentence
+now has a canonical page. The runtime half (shadow / replay / compare) is
+ArkRun and in-memory. **No required config migration.** Does not close `K01` /
+`Z09`.
+
+**Status: published** (on npm `latest`; see `docs/releases/4.8.5.md`).
+
+### Added
+- **`docs/arkorder.md`:** named APIs adopters were redesigning (`createOrderPlane`,
+  `IngestEscalate`, `Projector`, `maxXiKeys`, `ProposeResult`, `XiSchema`,
+  `xiKeys`, four verbs). Ships in the npm tarball. [ADR 0033](docs/adr/0033-arkorder-runtime-half-is-arkrun.md):
+  shadow/replay/provenance belong to ArkRun.
+- **Information budget** (`createOrderPlane({ informationBudget })`, not a
+  config key) — a scale may not observe a denied kind
+  (`ARKORDER_INFORMATION_BUDGET`).
+- **σ freshness, never ξ** — `createOrderPlane({ sigmaMaxAgeMs })` /
+  `σ.freshUntil`; age falls back to `release.releasedAt` when σ has no
+  timestamp. ξ keys named ttl/freshUntil/maxAge fail
+  (`ARKORDER_XI_TTL`, `ARKORDER_STALE_SIGMA`).
+- **`IngestEscalate.target`** including `human`.
+- **ArkRun** `shadowInformationPackage` / `compareInformationPackages` /
+  `replayInformationPackages` — in-memory, not a bus, not durable.
+- **`--antigravity-home`:** monotonic install into `$ANTIGRAVITY_HOME/skills`
+  (default `~/.gemini/config/skills`). `--agent-homes` includes it. Unlike
+  Claude/Grok homes, this catalog is the machine floor for every workspace.
+
+### Changed
+- Extra activation is one shape (`mode` + `managedLayers`). Roots stay distinct:
+  `arkOrder.planeRoots` vs `arkRun.kernelRoots` (`compositionRoots` alias).
+  `ark-check --sensors` lists both extras in one table.
+- Default `--install-agent-gates` host set includes `antigravity` when nothing
+  is detected.
+
 ## 4.8.4 — 2026-08-30
 
-**Status: pending publish** (see `docs/releases/4.8.4.md`).
+**Status: published** (see `docs/releases/4.8.4.md`).
 
 **Patch** over **4.8.3**. Invariant coverage stops hiding its own limits: the scan budget and the
 test globs are config, every discarded file is counted in the diagnostic, and coverage stops
@@ -249,7 +316,7 @@ repo paths living in strings, comments and docstrings that a rename left behind.
 
 **Patch** over **4.8.2**. Persistence writes in a use-case skip the aggregate (`writes-via-aggregate`). ArkOrder **`xiKeys`** names the slow product decisions; a managed-layer Prisma/pg write of those keys is `ARKORDER_XI_FIELD_WRITE`. Dead sensors (`too-many-params`, `ingest-writes-xi`) now emit. No new skill names. Does not close `K01` / `Z09`. **No required config migration.**
 
-**Status: published** (on npm `latest`; see `docs/releases/4.8.3.md`).
+**Status: published** (see `docs/releases/4.8.3.md`).
 
 ### Added
 - **`writes-via-aggregate`:** tier-1 structure sensor (ADR 0032). Direct evidence = persistence driver import **and** a write token (`.insert` / `.create` / `INSERT INTO` / …). Default advisory; promotable. Absence of the rule is silent.

package/README.md

@@ -29,13 +29,15 @@ Works with Cursor, Claude, Codex, and Grok.
 
 </div>
 
-> **ArkGate 4.8.4** is the current tree; **4.8.3** is on npm `latest`. Write. Check. Ship. Adopted = required GitHub
+> **ArkGate 4.8.5** is on npm `latest`. This tree is **4.8.6** (prepared patch; not published).
+> Write. Check. Ship. Adopted = required GitHub
 > status running `arkgate-check --strict-merge`, or an explicit `advisory-only` stance.
 > Status is compact (`arkgate-check --doctor`; `--all` for Details). Optional **ArkRun**
 > (`arkgate/runtime`) is an in-memory runtime — not Postgres. Optional **ArkOrder**
-> (`arkgate/order`) stops the agent rewriting the few slow product decisions as CRUD.
+> (`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.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.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)
 
 ---
 
@@ -104,7 +106,7 @@ once you adopt. The other three are optional.
 | **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 the agent rewriting the few slow product decisions as CRUD (`arkgate/order`) | Off unless you turn it on |
+| **ArkOrder** | Stops the agent rewriting the few slow product decisions as CRUD (`arkgate/order`). Valve: first `release()`, later ξ is `proposeRelease` then `apply` | 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
@@ -238,8 +240,8 @@ npx arkgate-check --path-drift --base-ref origin/main   # stale paths in strings
 npx arkgate-check --sensors        # which sensors can EVER be enforced, and which of your rules can be promoted
 npx arkgate-check --promote        # what enforcing each advisory rule would cost, from one run
 npx arkgate-check --strict-merge   # CI / required status
-npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
-# optional: refresh shared home skills (Claude/Grok/Codex; never downgrades)
+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)
 # npx skills add ./node_modules/arkgate/templates/agent-skills
@@ -280,14 +282,18 @@ because “what may be the plan” was never a rule.
 
 **ArkOrder** (`arkgate/order`) is that rule. Off unless you add `arkOrder`.
 Name the slow keys (`xiKeys`: plan, protocol, cost-code bound — not `projectId`).
-Posting an invoice is absorbed. Changing plan is a new release, with a blast
-radius. A generic `update` of the plan does not land. A use-case that PATCHes
-those keys through Prisma is named. Same npm package.
+Posting an invoice is absorbed. Changing plan is `proposeRelease` then `apply`.
+`refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`;
+capacity pack as data; in-memory `ReleaseStore`; `ingestTravelAction`; ArkRun
+`decisionTape`. A generic `update` of the plan does not land. A use-case that
+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:
-[configuration](docs/configuration.md) · [package surface](docs/package-surface.md).
+[ArkOrder](docs/arkorder.md) · [configuration](docs/configuration.md) ·
+[package surface](docs/package-surface.md).
 
 ---
 
@@ -303,7 +309,10 @@ 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) |
-| Current published (4.8.3 on npm `latest`) | [docs/releases/4.8.3.md](docs/releases/4.8.3.md) · [CHANGELOG](CHANGELOG.md) |
+| Tree prepared (4.8.6, not published) | [docs/releases/4.8.6.md](docs/releases/4.8.6.md) · [CHANGELOG](CHANGELOG.md) |
+| Current published (4.8.5 on npm `latest`) | [docs/releases/4.8.5.md](docs/releases/4.8.5.md) · [CHANGELOG](CHANGELOG.md) |
+| Prior published (4.8.4) | [docs/releases/4.8.4.md](docs/releases/4.8.4.md) |
+| Prior published (4.8.3) | [docs/releases/4.8.3.md](docs/releases/4.8.3.md) |
 | Prior published (4.8.2) | [docs/releases/4.8.2.md](docs/releases/4.8.2.md) |
 | Prior published (4.8.1) | [docs/releases/4.8.1.md](docs/releases/4.8.1.md) |
 | Prior published (4.8.0) | [docs/releases/4.8.0.md](docs/releases/4.8.0.md) |

package/bin/lib/agent-homes.mjs

@@ -1,6 +1,8 @@
 /**
- * Shared agent home skill catalogs (Claude / Grok), Codex-parity monotonic install.
- * Repo catalogs stay per-project; these homes are the machine floor (never downgrade).
+ * Shared agent home skill catalogs (Claude / Grok / Antigravity), Codex-parity
+ * monotonic install. Repo catalogs stay per-project; these homes are the
+ * machine floor (never downgrade). Antigravity's official global catalog is
+ * `~/.gemini/config/skills` — not pruned when a project `.agents/skills` exists.
  */
 import fs from 'node:fs';
 import os from 'node:os';
@@ -23,7 +25,7 @@ import {
   skillInstallLine,
 } from './skill-write.mjs';
 
-/** @typedef {'claude'|'grok'} AgentHomeHost */
+/** @typedef {'claude'|'grok'|'antigravity'} AgentHomeHost */
 
 const HOSTS = {
   claude: {
@@ -40,6 +42,14 @@ const HOSTS = {
     defaultDirName: '.grok',
     flag: '--grok-home',
   },
+  antigravity: {
+    id: 'antigravity',
+    label: 'Antigravity',
+    envKey: 'ANTIGRAVITY_HOME',
+    // Official global catalog is ~/.gemini/config/skills (docs/skills).
+    defaultDirName: path.join('.gemini', 'config'),
+    flag: '--antigravity-home',
+  },
 };
 
 export function agentHomeHostIds() {
@@ -62,6 +72,18 @@ export function grokSkillsDir(env = process.env, homeDir = os.homedir()) {
   return path.join(grokHomeDir(env, homeDir), 'skills');
 }
 
+export function antigravityHomeDir(env = process.env, homeDir = os.homedir()) {
+  return resolveHomeDir(HOSTS.antigravity, env, homeDir);
+}
+
+export function antigravitySkillsDir(env = process.env, homeDir = os.homedir()) {
+  return path.join(antigravityHomeDir(env, homeDir), 'skills');
+}
+
+export function usesDefaultAntigravityHome(env = process.env, homeDir = os.homedir()) {
+  return usesDefaultHome(HOSTS.antigravity, env, homeDir);
+}
+
 export function usesDefaultClaudeHome(env = process.env, homeDir = os.homedir()) {
   return usesDefaultHome(HOSTS.claude, env, homeDir);
 }
@@ -85,7 +107,8 @@ function usesDefaultHome(spec, env, homeDir) {
 }
 
 function skillsDirFor(host, env = process.env) {
-  return host === 'grok' ? grokSkillsDir(env) : claudeSkillsDir(env);
+  const spec = HOSTS[host];
+  return path.join(resolveHomeDir(spec, env), 'skills');
 }
 
 function readHomeCatalogFloor(skillsDir) {
@@ -124,7 +147,7 @@ function homeInPlay(parity, catalogState) {
 }
 
 /**
- * Detect Claude/Grok user-home ark-* catalogs that lag this package.
+ * Detect Claude/Grok/Antigravity user-home ark-* catalogs that lag this package.
  * Absent homes are not debt. Stamp-only body-match is not content-behind
  * (assessSkillCatalogParity already treats identity match as current).
  *
@@ -199,11 +222,13 @@ export function detectAgentHomeGaps(root, env = process.env) {
 /**
  * Claude home is loaded by Claude Code and often by Cursor. Treat both as in-session.
  * Grok home is urgent only on a Grok session (or when ARK_ACTIVE_HOST=grok).
+ * Antigravity global catalog is urgent on an Antigravity session (agy / ANTIGRAVITY).
  */
 export function agentHomeConcernIsActive(host, env = process.env) {
   const active = detectActiveAgentHost(env);
   if (host === 'claude') return active === 'claude' || active === 'cursor' || !active;
   if (host === 'grok') return active === 'grok' || !active;
+  if (host === 'antigravity') return active === 'antigravity' || !active;
   return true;
 }
 
@@ -223,6 +248,7 @@ export function agentHomeRefreshCommand(root, gap) {
  *   force?: boolean,
  *   claudeHome?: boolean,
  *   grokHome?: boolean,
+ *   antigravityHome?: boolean,
  *   agentHomes?: boolean,
  *   json?: boolean,
  *   env?: NodeJS.ProcessEnv,
@@ -233,13 +259,22 @@ export function installRequestedAgentHomes(args) {
   const env = args.env ?? process.env;
   const wantClaude = Boolean(args.claudeHome || args.agentHomes);
   const wantGrok = Boolean(args.grokHome || args.agentHomes);
-  if (!wantClaude && !wantGrok) return [];
+  const wantAntigravity = Boolean(args.antigravityHome || args.agentHomes);
+  if (!wantClaude && !wantGrok && !wantAntigravity) return [];
   const skills = args.skills ?? skillTemplates();
   const version = args.version ?? arkPackageVersion();
   const installed = [];
   const targets = [
     wantClaude ? { host: 'claude', spec: HOSTS.claude, dir: claudeSkillsDir(env), usesDefault: usesDefaultClaudeHome(env) } : null,
     wantGrok ? { host: 'grok', spec: HOSTS.grok, dir: grokSkillsDir(env), usesDefault: usesDefaultGrokHome(env) } : null,
+    wantAntigravity
+      ? {
+          host: 'antigravity',
+          spec: HOSTS.antigravity,
+          dir: antigravitySkillsDir(env),
+          usesDefault: usesDefaultAntigravityHome(env),
+        }
+      : null,
   ].filter(Boolean);
 
   for (const target of targets) {