arkgate 4.8.7 → 4.8.9

package/docs/package-surface.md

@@ -2,6 +2,18 @@
 
 **Write. Check. Ship.**
 **When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.**
+
+Not an API Gateway. Not a folder linter. If the check is not required on the PR, the config
+is just documentation.
+
+AI can build fast—and make a mess just as fast.
+
+Keep the product easy to understand, change, and trust.
+
+ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+
+Safer changes, fewer surprises, and extra protection only when you choose it.
+
 That is the product wedge (host hook + required CI). Skills name the next step after that.
 **Not the wedge:** the optional in-process **ArkRun** runtime (`arkgate/runtime`) and the
 optional **ArkOrder** pattern extra (`arkgate/order`).
@@ -25,7 +37,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`) | 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). |
+| **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. |
 | **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`. |
@@ -177,9 +189,9 @@ claims. Static architecture enforcement does not depend on them.
 
 | Surface | Import path | Notes |
 |---------|-------------|--------|
-| **ArkRun kernel** | **`arkgate/runtime`** | Public brand **ArkRun**. Same npm package `arkgate` (ADR 0031). Factory `createStrictArkKernel` (each call is an isolated instance; no process-wide `getKernel()` singleton). Root export does **not** include the factory. Optional extra `arkRun` on schema `1.2+`. Event bus, intents, policies, sagas, event buffer, projections, and strict helpers. Managed components declare `uses` / `reactsTo` / `raises` / `sends` on `register()`; `getDependencyInformationPackage()` is a JSON snapshot of ids, lifetime, and declarations and never includes factories, live instances, or input DTOs (ADR 0023). `requestGraph()` slices that snapshot into **process** or **technical** graphs with optional `nodeIds`, `degreesOfSeparation`, and include/exclude query; `formatArkRunGraphMermaid()` (also `graph.mermaid`) is a helper string, never a score. `send()` is the transport port (local / localBlocking / broker); missing broker falls back to in-process local delivery, `ephemeral` defaults true, and **no cloud SDKs ship** in the package (ADR 0024). Opt-in `startInspector()` / `startArkRunInspector()` binds **`127.0.0.1` only**, refuses `NODE_ENV=production`, lazy-loads HTTP, and serves JSON snapshots, SSE, and `/graph` slices of the information package (no public / authless bind). **Shadow / replay / compare** (`shadowInformationPackage`, `compareInformationPackages`, `replayInformationPackages`) are in-memory helpers on that snapshot — not durable, not a second bus (ADR 0033). **Decision tape** `decisionTape` `{ xiHash, event, residual }` via `appendDecisionTape` (ADR 0034). Built-in stores are **InMemory reference only**. Branding ArkRun is not a production-durability claim. **`@arkgate/runtime` is deprecated** leftover 0.x (`experimental` dist-tag). |
+| **ArkRun kernel** | **`arkgate/runtime`** | Public brand **ArkRun**. Same npm package `arkgate` (ADR 0031). Factory `createStrictArkKernel` (each call is an isolated instance; no process-wide `getKernel()` singleton). Root export does **not** include the factory. Optional extra `arkRun` on schema `1.2+`. Event bus, intents, policies, sagas, event buffer, projections, and strict helpers. Managed components declare `uses` / `reactsTo` / `raises` / `sends` on `register()`; `getDependencyInformationPackage()` is a JSON snapshot of ids, lifetime, and declarations and never includes factories, live instances, or input DTOs (ADR 0023). `requestGraph()` slices that snapshot into **process** or **technical** graphs with optional `nodeIds`, `degreesOfSeparation`, and include/exclude query; `formatArkRunGraphMermaid()` (also `graph.mermaid`) is a helper string, never a score. `send()` is the transport port (local / localBlocking / broker); missing broker falls back to in-process local delivery, `ephemeral` defaults true, and **no cloud SDKs ship** in the package (ADR 0024). Opt-in `startInspector()` / `startArkRunInspector()` binds **`127.0.0.1` only**, refuses `NODE_ENV=production`, lazy-loads HTTP, and serves JSON snapshots, SSE, `/graph` slices of the information package, plus queue monitors **`GET /outbox`** and **`GET /workflows`** (full counts + sanitized samples capped at 32; no full event payloads; missing ports are unavailable; no public / authless bind). Snapshot `hardening.durability` classifies the explicit outbox/audit/workflow store ports; default `InMemory*` stores stay visibly `memory`, never durable. Dual bins **`ark-dashboard`** / **`arkgate-dashboard`** poll those JSON facts (ANSI TUI in `bin/` only — presentation is not in the kernel); `ark dashboard` / `arkgate dashboard` dispatch to the same executable. **Shadow / replay / compare** (`shadowInformationPackage`, `compareInformationPackages`, `replayInformationPackages`) are in-memory helpers on that snapshot — not durable, not a second bus (ADR 0033). **Decision tape** `decisionTape` `{ xiHash, event, residual }` via `appendDecisionTape` (ADR 0034). Built-in stores are **InMemory reference only**. Branding ArkRun is not a production-durability claim. **`@arkgate/runtime` is deprecated** leftover 0.x (`experimental` dist-tag). |
 | **NestJS adapter** | **`arkgate/nestjs`** | Experimental optional peer `@nestjs/common` for the ArkRun kernel. Same npm package. `@arkgate/runtime/nestjs` is deprecated. |
-| **ArkOrder plane** | **`arkgate/order`** | Public brand **ArkOrder**. Same npm package `arkgate` (ADR 0030) — not `@arkgate/order`. Factory `createOrderPlane`. Valved verbs: `release` / `project` / `ingest` / `proposeRelease` / `apply` / `refreshSigma`. No `update`. First freeze is `release()`; later ξ change is `apply` (`ARKORDER_UNVALVED_RELEASE`). Haken: few slow keys; ingest residual `absorb | escalate_up | hold` + closed `reasonCode`; empty blast fails closed. Capacity pack as data (`kind` / `sigmaKey` / `payloadKey` / `op`). Factory options (not config keys): `informationBudget.cannotObserve`, `sigmaMaxAgeMs`, `store` (`ReleaseStore` / `createMemoryReleaseStore`), `catalogDigest`. Thin travel: `ingestTravelAction` absorb→`send` / escalate_up human→`raises`. `IngestEscalate.target` includes `human`. Root `arkgate` export does **not** include the factory. Optional extra `arkOrder` on schema `1.3`. In-memory; not durable; does not close K01. Does not replace ArkRun. Runtime half (shadow/replay/compare + `decisionTape` / `appendDecisionTape`) is ArkRun (ADR 0033 / 0034). Canonical: [ArkOrder](arkorder.md). |
+| **ArkOrder plane** | **`arkgate/order`** | Public brand **ArkOrder**. Same npm package `arkgate` (ADR 0030) — not `@arkgate/order`. Factory `createOrderPlane`. Valved verbs: `release` / `project` / `ingest` / `proposeRelease` / `apply` / `refreshSigma` / `restore`. No `update`. First freeze is `release()`; later ξ change is `apply` (`ARKORDER_UNVALVED_RELEASE`). `restore(release)` installs a previously frozen `Release` (hash remains identity; not durable). `hashOf` / `hashReleasePayload` verify a stored hash without a second freeze. Default Kernel clock is `Date.now()`. Optional `arkOrder.appliesTo` globs; `maxXiKeys` caps one `release()`, not `xiKeys.length`. Haken: few slow keys; ingest residual `absorb | escalate_up | hold` + closed `reasonCode`; empty blast fails closed. Capacity pack as data (`kind` / `sigmaKey` / `payloadKey` / `op`). Factory options (not config keys): `informationBudget.cannotObserve`, `sigmaMaxAgeMs`, `store` (`ReleaseStore` / `createMemoryReleaseStore`), `catalogDigest`. Thin travel: `ingestTravelAction` absorb→`send` / escalate_up human→`raises`. `IngestEscalate.target` includes `human`. Root `arkgate` export does **not** include the factory. Optional extra `arkOrder` on schema `1.3`. In-memory; not durable; does not close K01. Does not replace ArkRun. Runtime half (shadow/replay/compare + `decisionTape` / `appendDecisionTape`) is ArkRun (ADR 0033 / 0034). Billing gallery is git-only: [examples/arkorder-billing](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing) (not in the npm tarball). Canonical: [ArkOrder](arkorder.md). |
 
 ---
 
@@ -189,7 +201,7 @@ claims. Static architecture enforcement does not depend on them.
 import { createAICodeGate } from 'arkgate';
 import { createStrictArkKernel, createStrictArkKernelFromConfig } from 'arkgate/runtime';
 import { ArkModule, InjectArk } from 'arkgate/nestjs';
-import { createOrderPlane } from 'arkgate/order';
+import { createOrderPlane, hashOf } from 'arkgate/order';
 ```
 
 One install: `npm install arkgate`. `@arkgate/runtime` is deprecated.
@@ -253,8 +265,10 @@ 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 prepared: [4.8.7.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.7.md);
-current published: [4.8.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.6.md);
+(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);
+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);
 prior published: [4.8.4.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.4.md);
 prior published: [4.8.3.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.3.md);

package/docs/product-voice.md

@@ -45,12 +45,15 @@ human copy says **status**.
 
 ## Locked first-contact
 
-On README, use, develop, the docs hub, and the product site:
+On the eight canonical public openings — `README.md`, `docs/use.md`,
+`docs/develop.md`, `docs/README.md`, `docs/enthusiast/README.md`,
+`docs/agent-guide.md`, `docs/ai-gates.md`, and `docs/package-surface.md` — use:
 
 1. **Verbs:** `Write. Check. Ship.`
 2. **Deny:** `When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.`
 3. **Not-that (below the fold, one line):** `Not an API Gateway. Not a folder linter. If the check is not required on the PR, the config is just documentation.`
-4. **Nouns (once, below the deny):** ArkGate is import rules. ArkRules is optional policies. ArkRun is an optional experimental runtime. ArkOrder is the extra that stops the agent from rewriting the few slow product decisions (plan, protocol) as CRUD — named when the consumer opts in, never as the first noun.
+4. **Story:** the exact four-paragraph introduction below, with no visible heading or labels.
+5. **Technical nouns (below the introduction):** ArkGate is import rules. ArkRules is optional policies. ArkRun is an optional experimental runtime. ArkOrder is the extra that stops the agent from rewriting the few slow product decisions (plan, protocol) as CRUD — named when the consumer opts in, never as the first noun.
 
 Do not lead with folders, `ark.config.json`, “contract”, “gate”, “house”, or “doctor”
 as the first noun. Historical: `If the AI writes an illegal import, the write is rejected`
@@ -61,6 +64,26 @@ ADR 0001 keeps the public name **ArkGate**.
 
 ---
 
+## Unlabeled four-paragraph introduction
+
+STAR is an internal writing method only. Public openings never print the formula's
+name, a heading for this block, bullets, or Situation/Task/Action/Result labels.
+Use these exact four paragraphs and put technical precision below them.
+
+AI can build fast—and make a mess just as fast.
+
+Keep the product easy to understand, change, and trust.
+
+ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+
+Safer changes, fewer surprises, and extra protection only when you choose it.
+
+Do not add technical terms to these four paragraphs. In the next section, explain that
+ArkGate checks imports, ArkRules is optional, ArkRun is experimental and in-memory,
+and ArkOrder is optional and for a few slow product decisions.
+
+---
+
 ## How it sounds
 
 Short. Product nouns. Scene English (Vercel / Supabase / GitHub Checks).

package/docs/use.md

@@ -2,13 +2,21 @@
 
 **Write. Check. Ship.**
 
-For **anyone** shipping TypeScript with an AI coding agent.
-
 **When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.**
 
 Not an API Gateway. Not a folder linter. If the check is not required on the PR, the config
 is just documentation.
 
+AI can build fast—and make a mess just as fast.
+
+Keep the product easy to understand, change, and trust.
+
+ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+
+Safer changes, fewer surprises, and extra protection only when you choose it.
+
+For **anyone** shipping TypeScript with an AI coding agent.
+
 ---
 
 ## In one minute
@@ -81,7 +89,7 @@ The config only binds when the write doesn’t land and CI is required.
 | **ArkGate** (layers) | Import rules. The write doesn’t land. The PR fails. | Always — this is the product |
 | **ArkRules** | Optional policies *inside* a layer. | Off until you turn it on (start may ship advisory templates) |
 | **ArkRun** | Optional experimental runtime (`arkgate/runtime`) | Off. In-memory. Not Postgres. |
-| **ArkOrder** | Stops the agent rewriting the few slow product decisions as CRUD (`arkgate/order`). Library + sensors, [not a service](arkorder.md). Valve: `proposeRelease` then `apply`; `refreshSigma`; ingest residual; capacity pack; `ReleaseStore`; ArkRun `decisionTape`. ArkOrder freezes the pattern through a valve. ArkRun is how the residual travels. | Off. Name `xiKeys` (plan / protocol, not `projectId`). Invoices and seats still flow. In-memory. Not durable. |
+| **ArkOrder** | Stops the agent rewriting the few slow product decisions as CRUD (`arkgate/order`). Library + sensors, [not a service](arkorder.md). Valve: `proposeRelease` then `apply`; `refreshSigma`; ingest residual; capacity pack; `ReleaseStore`; ArkRun `decisionTape`. ArkOrder freezes the pattern through a valve. ArkRun is how the residual travels. | Off. Name `xiKeys` (plan / protocol, not `projectId`). Derive recomputable statuses; invoices and seats still flow. In-memory. Not durable. |
 
 Start always gives you **layers**. Compact starters do **not** turn on ArkRun or
 ArkOrder. No extras is fine — only ArkGate runs. Leftovers are labeled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.8.7",
+  "version": "4.8.9",
   "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",
@@ -55,9 +55,11 @@
   "bin": {
     "arkgate": "bin/ark.mjs",
     "arkgate-check": "bin/ark-check.mjs",
+    "arkgate-dashboard": "bin/ark-dashboard.mjs",
     "arkgate-mcp": "bin/ark-mcp.mjs",
     "ark": "bin/ark.mjs",
     "ark-check": "bin/ark-check.mjs",
+    "ark-dashboard": "bin/ark-dashboard.mjs",
     "ark-mcp": "bin/ark-mcp.mjs"
   },
   "mcpName": "io.github.pedroknigge/arkgate",

package/schemas/ark.config.schema.json

@@ -954,6 +954,15 @@
           },
           "uniqueItems": true,
           "default": []
+        },
+        "appliesTo": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true,
+          "default": []
         }
       }
     }

package/server.json

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

package/templates/agent-skills/README.md

@@ -7,7 +7,7 @@
 This directory is the **Agent Skills–compatible** packaging of the same **13**
 `/ark-*` skills shipped as flat templates for Ark install. **No new skill names.**
 
-Package version when last generated context: **arkgate@4.8.6**
+Package version when last generated context: **arkgate@4.8.9**
 Schema: agent-skills package contract `1.0`
 
 ## Skills (frozen catalog)

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

@@ -187,6 +187,7 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 ```
 
 - `xiKeys` are meaning, not membership. `projectId` / `orgId` do not belong. If `proposeRelease` throws empty blast, that key does not order anything. After the first `release()`, change ξ with `proposeRelease` then `apply` — not a second `release()` (`ARKORDER_UNVALVED_RELEASE`). `refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`; capacity pack as data; `createMemoryReleaseStore`; `ingestTravelAction`; ArkRun `decisionTape`.
+- Before writing a name, drop the candidate and ask: can current σ and s reconstruct it uniquely? Then ask direction: does the key slave ingest, or does ingest determine the status? If it is recomputable or ingest determines it (`paid`, `overdue`, `atCapacity`, or `approved` folded from signatures), derive it as a projection or ingest fold; invoices and seats stay on ingest. The check remains silent on semantic entailment.
 - A use-case that `prisma.*.update({ plan })` while `plan` is in `xiKeys` is **[ArkOrder]** `ARKORDER_XI_FIELD_WRITE`. Invoices and seats still flow through `ingest`.
 
 - Do **not** put `arkOrder` on the compact starter / `ark start` scaffold. Domain stays plane-free. Import `createOrderPlane` from `arkgate/order` (same npm package).

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

@@ -147,7 +147,7 @@ When `arkRun` is present:
 
 ### Autopilot + ArkOrder
 When `arkOrder` is present:
-- Grind skip clusters with judgment: `ARKORDER_MISSING_PLANE` / `ARKORDER_KERNEL_IN_DOMAIN` / `ARKORDER_GENERIC_UPDATE` / `ARKORDER_TOO_MANY_PARAMS` / `ARKORDER_INGEST_WRITES_XI` / `ARKORDER_XI_FIELD_WRITE` / `ARKORDER_UNVALVED_RELEASE`. First freeze with `release()`; later ξ change is `proposeRelease` then `apply`. `refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`; capacity pack; `createMemoryReleaseStore`; `ingestTravelAction`; ArkRun `decisionTape`. Never `update`/`patch`/`set`. Name `xiKeys`; do not persist those keys from a use-case. Doctor / status `arkOrder` is `notAScore`.
+- Grind skip clusters with judgment: `ARKORDER_MISSING_PLANE` / `ARKORDER_KERNEL_IN_DOMAIN` / `ARKORDER_GENERIC_UPDATE` / `ARKORDER_TOO_MANY_PARAMS` / `ARKORDER_INGEST_WRITES_XI` / `ARKORDER_XI_FIELD_WRITE` / `ARKORDER_UNVALVED_RELEASE`. First freeze with `release()`; later ξ change is `proposeRelease` then `apply`. `refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`; capacity pack; `createMemoryReleaseStore`; `ingestTravelAction`; ArkRun `decisionTape`. Never `update`/`patch`/`set`. Name `xiKeys`; do not persist those keys from a use-case. Do not “fix” a derived status by adding it to `xiKeys`; that institutionalizes the skip, so derive it on read or fold it from ingest. Doctor / status `arkOrder` is `notAScore`.
 - Extra off → `/ark-adopt` (advisory). Do not invent `/ark-order`.
 - Skills never enforce.
 

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

@@ -45,7 +45,7 @@ Label findings **`[Layer]`** vs **`[ArkRules]`** vs **`[ArkRun]`** vs **`[ArkOrd
 
 Application / Features may declare advisory **`writes-via-aggregate`**: a use-case that imports a persistence driver and calls `.insert` / `.create` / `INSERT INTO` is the skip. Persistence adapters stay the write edge. Do not add `Externals/` or `admission.ts` as contract law.
 
-When `arkOrder` is on, name **`xiKeys`** (3–5 slow product decisions). Membership ids are not keys. A use-case that persists those keys is `ARKORDER_XI_FIELD_WRITE`. First freeze is `release()`; later ξ is `proposeRelease` then `apply`; `refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`; capacity pack as data; in-memory `ReleaseStore`; ArkRun `decisionTape`. Copy [examples/arkorder-billing/](../../../examples/arkorder-billing/) and rename the three keys.
+When `arkOrder` is on, name **`xiKeys`** (3–5 slow product decisions). Membership ids and recomputable statuses are not keys: derive a status on read or fold it from ingest instead. A use-case that persists those keys is `ARKORDER_XI_FIELD_WRITE`. First freeze is `release()`; later ξ is `proposeRelease` then `apply`; `refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`; capacity pack as data; in-memory `ReleaseStore`; ArkRun `decisionTape`. The billing gallery 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. The check remains silent on semantic entailment.
 
 ## Subagent fan-out (optional, host-dependent)
 

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

@@ -168,7 +168,7 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 ### Explore + extras
 - Map extras when present; never write `arkRun` / `arkOrder`. Extra off → residual `n/a` / silent.
 - When `arkOrder` is on, name the valve: first freeze `release()`; later ξ is `proposeRelease` then `apply`; `refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`; capacity pack as data; in-memory `ReleaseStore` (`createMemoryReleaseStore`); thin travel `ingestTravelAction`. ArkRun residual may include information package `decisionTape` `{ xiHash, event, residual }`.
-- Field path may name `examples/arkorder-billing/` (ArkOrder fixture — map only). First extra write is `/ark-adopt`; grind is `/ark-autopilot`.
+- Field path may name the ArkOrder gallery on GitHub (`https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing`; not in the npm tarball — map only). First extra write is `/ark-adopt`; grind is `/ark-autopilot`.
 
 ## Output mode (pick one — do not invent a fourth)
 
@@ -297,7 +297,7 @@ When `examples/`, `templates/`, gallery starters, eval fixtures, or docs claim
 3. Diff **rule strength** across archetypes (missing denies = soft false-green for consumers).
 4. Note import style vs package surface docs (`arkgate` root barrel vs preferred subpath).
 5. Flag **false promises**: demo fails under its own check, or green with a hollow contract.
-6. When extras are on, label residual `[ArkRun]` / `[ArkOrder]`. Field path may name `examples/arkorder-billing/`. Never write extras from this skill.
+6. When extras are on, label residual `[ArkRun]` / `[ArkOrder]`. Field path may name the ArkOrder gallery on GitHub (`https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing`; not in the npm tarball). Never write extras from this skill.
 
 If the repo is a **pure app** (no examples): state **Field path: internal** and do one of:
 - Name the **norm for new code** that the residual implies (e.g. “no new `platform/db` in routes”), or

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

@@ -157,6 +157,7 @@ When `arkOrder` is present on the architecture config:
 - First freeze ξ with `release()`; later ξ change is `proposeRelease` then `apply` (`ARKORDER_UNVALVED_RELEASE`). `refreshSigma` for saldo. Field `ingest()` returns `absorb | escalate_up | hold` bound to `xiHash` + `reasonCode`; never a Release. Capacity pack as data; `createMemoryReleaseStore`; `ingestTravelAction`; ArkRun `decisionTape`. No `update`/`patch`/`set`.
 - Call the factory only inside `arkOrder.planeRoots`. Empty roots in `enforced` mode is `ARKORDER_MISSING_PLANE`.
 - Named slow keys live in `arkOrder.xiKeys`. A managed-layer Prisma/pg write of those keys is `ARKORDER_XI_FIELD_WRITE` — absorb with `ingest` or change the pattern with `proposeRelease` then `apply`.
+- A recomputable status is not a new `xiKeys` entry or a `proposeRelease`: place it as a read projection or an ingest fold. If slow-key naming remains unresolved, return to `/ark-adopt` and run the elimination test before writing the config.
 - Skip clusters (`ARKORDER_MISSING_PLANE` / `ARKORDER_KERNEL_IN_DOMAIN` / `ARKORDER_GENERIC_UPDATE` / `ARKORDER_TOO_MANY_PARAMS` / `ARKORDER_INGEST_WRITES_XI` / `ARKORDER_XI_FIELD_WRITE`): place this artifact, then grind via `/ark-autopilot`. Extra not on → `/ark-adopt`. Do not invent `/ark-order`.
 - Absence of the extra is valid. Do not invent `/ark-order`. Skills never enforce.
 

package/templates/skills/ark-adopt.md

@@ -187,6 +187,7 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 ```
 
 - `xiKeys` are meaning, not membership. `projectId` / `orgId` do not belong. If `proposeRelease` throws empty blast, that key does not order anything. After the first `release()`, change ξ with `proposeRelease` then `apply` — not a second `release()` (`ARKORDER_UNVALVED_RELEASE`). `refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`; capacity pack as data; `createMemoryReleaseStore`; `ingestTravelAction`; ArkRun `decisionTape`.
+- Before writing a name, drop the candidate and ask: can current σ and s reconstruct it uniquely? Then ask direction: does the key slave ingest, or does ingest determine the status? If it is recomputable or ingest determines it (`paid`, `overdue`, `atCapacity`, or `approved` folded from signatures), derive it as a projection or ingest fold; invoices and seats stay on ingest. The check remains silent on semantic entailment.
 - A use-case that `prisma.*.update({ plan })` while `plan` is in `xiKeys` is **[ArkOrder]** `ARKORDER_XI_FIELD_WRITE`. Invoices and seats still flow through `ingest`.
 
 - Do **not** put `arkOrder` on the compact starter / `ark start` scaffold. Domain stays plane-free. Import `createOrderPlane` from `arkgate/order` (same npm package).

package/templates/skills/ark-autopilot.md

@@ -147,7 +147,7 @@ When `arkRun` is present:
 
 ### Autopilot + ArkOrder
 When `arkOrder` is present:
-- Grind skip clusters with judgment: `ARKORDER_MISSING_PLANE` / `ARKORDER_KERNEL_IN_DOMAIN` / `ARKORDER_GENERIC_UPDATE` / `ARKORDER_TOO_MANY_PARAMS` / `ARKORDER_INGEST_WRITES_XI` / `ARKORDER_XI_FIELD_WRITE` / `ARKORDER_UNVALVED_RELEASE`. First freeze with `release()`; later ξ change is `proposeRelease` then `apply`. `refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`; capacity pack; `createMemoryReleaseStore`; `ingestTravelAction`; ArkRun `decisionTape`. Never `update`/`patch`/`set`. Name `xiKeys`; do not persist those keys from a use-case. Doctor / status `arkOrder` is `notAScore`.
+- Grind skip clusters with judgment: `ARKORDER_MISSING_PLANE` / `ARKORDER_KERNEL_IN_DOMAIN` / `ARKORDER_GENERIC_UPDATE` / `ARKORDER_TOO_MANY_PARAMS` / `ARKORDER_INGEST_WRITES_XI` / `ARKORDER_XI_FIELD_WRITE` / `ARKORDER_UNVALVED_RELEASE`. First freeze with `release()`; later ξ change is `proposeRelease` then `apply`. `refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`; capacity pack; `createMemoryReleaseStore`; `ingestTravelAction`; ArkRun `decisionTape`. Never `update`/`patch`/`set`. Name `xiKeys`; do not persist those keys from a use-case. Do not “fix” a derived status by adding it to `xiKeys`; that institutionalizes the skip, so derive it on read or fold it from ingest. Doctor / status `arkOrder` is `notAScore`.
 - Extra off → `/ark-adopt` (advisory). Do not invent `/ark-order`.
 - Skills never enforce.
 

package/templates/skills/ark-contract.md

@@ -45,7 +45,7 @@ Label findings **`[Layer]`** vs **`[ArkRules]`** vs **`[ArkRun]`** vs **`[ArkOrd
 
 Application / Features may declare advisory **`writes-via-aggregate`**: a use-case that imports a persistence driver and calls `.insert` / `.create` / `INSERT INTO` is the skip. Persistence adapters stay the write edge. Do not add `Externals/` or `admission.ts` as contract law.
 
-When `arkOrder` is on, name **`xiKeys`** (3–5 slow product decisions). Membership ids are not keys. A use-case that persists those keys is `ARKORDER_XI_FIELD_WRITE`. First freeze is `release()`; later ξ is `proposeRelease` then `apply`; `refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`; capacity pack as data; in-memory `ReleaseStore`; ArkRun `decisionTape`. Copy [examples/arkorder-billing/](../../../examples/arkorder-billing/) and rename the three keys.
+When `arkOrder` is on, name **`xiKeys`** (3–5 slow product decisions). Membership ids and recomputable statuses are not keys: derive a status on read or fold it from ingest instead. A use-case that persists those keys is `ARKORDER_XI_FIELD_WRITE`. First freeze is `release()`; later ξ is `proposeRelease` then `apply`; `refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`; capacity pack as data; in-memory `ReleaseStore`; ArkRun `decisionTape`. The billing gallery 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. The check remains silent on semantic entailment.
 
 ## Subagent fan-out (optional, host-dependent)
 

package/templates/skills/ark-explore.md

@@ -168,7 +168,7 @@ ArkGate has **always-on Layers** plus opt-in extras. The user chooses extras; yo
 ### Explore + extras
 - Map extras when present; never write `arkRun` / `arkOrder`. Extra off → residual `n/a` / silent.
 - When `arkOrder` is on, name the valve: first freeze `release()`; later ξ is `proposeRelease` then `apply`; `refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`; capacity pack as data; in-memory `ReleaseStore` (`createMemoryReleaseStore`); thin travel `ingestTravelAction`. ArkRun residual may include information package `decisionTape` `{ xiHash, event, residual }`.
-- Field path may name `examples/arkorder-billing/` (ArkOrder fixture — map only). First extra write is `/ark-adopt`; grind is `/ark-autopilot`.
+- Field path may name the ArkOrder gallery on GitHub (`https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing`; not in the npm tarball — map only). First extra write is `/ark-adopt`; grind is `/ark-autopilot`.
 
 ## Output mode (pick one — do not invent a fourth)
 
@@ -297,7 +297,7 @@ When `examples/`, `templates/`, gallery starters, eval fixtures, or docs claim
 3. Diff **rule strength** across archetypes (missing denies = soft false-green for consumers).
 4. Note import style vs package surface docs (`arkgate` root barrel vs preferred subpath).
 5. Flag **false promises**: demo fails under its own check, or green with a hollow contract.
-6. When extras are on, label residual `[ArkRun]` / `[ArkOrder]`. Field path may name `examples/arkorder-billing/`. Never write extras from this skill.
+6. When extras are on, label residual `[ArkRun]` / `[ArkOrder]`. Field path may name the ArkOrder gallery on GitHub (`https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing`; not in the npm tarball). Never write extras from this skill.
 
 If the repo is a **pure app** (no examples): state **Field path: internal** and do one of:
 - Name the **norm for new code** that the residual implies (e.g. “no new `platform/db` in routes”), or

package/templates/skills/ark-place.md

@@ -157,6 +157,7 @@ When `arkOrder` is present on the architecture config:
 - First freeze ξ with `release()`; later ξ change is `proposeRelease` then `apply` (`ARKORDER_UNVALVED_RELEASE`). `refreshSigma` for saldo. Field `ingest()` returns `absorb | escalate_up | hold` bound to `xiHash` + `reasonCode`; never a Release. Capacity pack as data; `createMemoryReleaseStore`; `ingestTravelAction`; ArkRun `decisionTape`. No `update`/`patch`/`set`.
 - Call the factory only inside `arkOrder.planeRoots`. Empty roots in `enforced` mode is `ARKORDER_MISSING_PLANE`.
 - Named slow keys live in `arkOrder.xiKeys`. A managed-layer Prisma/pg write of those keys is `ARKORDER_XI_FIELD_WRITE` — absorb with `ingest` or change the pattern with `proposeRelease` then `apply`.
+- A recomputable status is not a new `xiKeys` entry or a `proposeRelease`: place it as a read projection or an ingest fold. If slow-key naming remains unresolved, return to `/ark-adopt` and run the elimination test before writing the config.
 - Skip clusters (`ARKORDER_MISSING_PLANE` / `ARKORDER_KERNEL_IN_DOMAIN` / `ARKORDER_GENERIC_UPDATE` / `ARKORDER_TOO_MANY_PARAMS` / `ARKORDER_INGEST_WRITES_XI` / `ARKORDER_XI_FIELD_WRITE`): place this artifact, then grind via `/ark-autopilot`. Extra not on → `/ark-adopt`. Do not invent `/ark-order`.
 - Absence of the extra is valid. Do not invent `/ark-order`. Skills never enforce.