arkgate 4.8.5 → 4.8.7

package/CHANGELOG.md

@@ -3,6 +3,60 @@
 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.7 — 2026-08-31
+
+**Patch** over **4.8.6**. Phase **LD** — layer description projection. Optional
+`layers[].description` is an **app-context caption** (what this folder is in the
+product), not architecture jargon. Place, doctor, coverage, and the HTML report
+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. Do not npm-publish from this item until the maintainer tag.
+
+**Status: prepared** (tree ready; npm `latest` remains **4.8.6** until publish).
+
+### Added
+- Public name for existing `layers[].description`. Example:
+  `"Purchase requests — from asked to received."`
+- Place / prepare-write / MCP JSON, doctor JSON + human, coverage JSON, and the
+  HTML Purpose column project the caption when present.
+- `/ark-adopt` writes the caption from the product map or glossary; `/ark-place`
+  prints it next to layer name + globs.
+
+### Changed
+- `policyHash` omits `layers[].description` the same way it omits `stewards`.
+  Caption-only is neutral. Absence stays silent: never a residual, never a
+  score, never `--strict-config` fail.
+
+## 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.
+
+**Status: published** (on npm `latest`; see `docs/releases/4.8.6.md`).
+
+### 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
@@ -11,7 +65,7 @@ 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: prepared** (not yet on npm `latest`).
+**Status: published** (see `docs/releases/4.8.5.md`).
 
 ### Added
 - **`docs/arkorder.md`:** named APIs adopters were redesigning (`createOrderPlane`,
@@ -41,7 +95,7 @@ ArkRun and in-memory. **No required config migration.** Does not close `K01` /
 
 ## 4.8.4 — 2026-08-30
 
-**Status: published** (on npm `latest`; 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

package/README.md

@@ -29,13 +29,15 @@ Works with Cursor, Claude, Codex, and Grok.
 
 </div>
 
-> **ArkGate 4.8.4** is on npm `latest`. Write. Check. Ship. Adopted = required GitHub
+> **ArkGate 4.8.6** is on npm `latest`.
+> 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
@@ -280,10 +282,13 @@ 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:
@@ -304,8 +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 tree (4.8.5 prepared) | [docs/releases/4.8.5.md](docs/releases/4.8.5.md) · [CHANGELOG](CHANGELOG.md) |
-| Current published (4.8.4 on npm `latest`) | [docs/releases/4.8.4.md](docs/releases/4.8.4.md) |
+| Current tree (4.8.7 prepared) | [docs/releases/4.8.7.md](docs/releases/4.8.7.md) · [CHANGELOG](CHANGELOG.md) |
+| Current published (4.8.6 on npm `latest`) | [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) |
 | 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) |

package/bin/ark-mcp-runtime.mjs

@@ -27,6 +27,7 @@ import { effectiveCapabilityDeny, stableSerialize } from './lib/analysis-engine.
 import { createImportTargetResolver } from './lib/import-resolve.mjs';
 import { validateWithAutoPatch, resolveImportFileAbs } from './lib/auto-patch.mjs';
 import { composePrepareWrite } from './lib/prepare-write.mjs';
+import { placementDescriptionFields } from './lib/layer-description.mjs';
 import { loadArkConfigContract } from './lib/config-contract.mjs';
 import { loadEffectiveArkRulesFromDisk } from './lib/effective-contract-load.mjs';
 import {
@@ -1925,6 +1926,7 @@ export async function runArkMcp({ hookInput } = {}) {
         'Place a file in the architecture: filePath is required (fail-closed without it — never invents components/*.tsx or defaults to Presentation). ' +
         'Returns layer, mayImport / mustNotImport, forbiddenGlobals, and goldenPattern ' +
         '(load-bearing for NEW code when .ark/golden-pattern.json exists — adopt generates it). ' +
+        'When the matched layer has layers[].description, the JSON includes description; the field is omitted when absent. ' +
         'Call BEFORE writing a new file. ' +
         'Prefer ark_prepare_write when you already have the source snippet (place+validate+autoPatch in one call).',
       inputSchema: {
@@ -1950,7 +1952,8 @@ export async function runArkMcp({ hookInput } = {}) {
         'mechanical-safe autoPatch + judgmentBrief when judgment is needed + contentHash for host commit. ' +
         'Also returns the versioned new/worsened designDelta for the proposed full file. ' +
         'Composes ark_place + write-gate — call BEFORE Write/Edit when you have the snippet. ' +
-        'Returns { filePath, layer, valid, violations?, autoPatch?, judgmentBrief?, contentHash, ... }.',
+        'When the matched layer has layers[].description, the JSON includes description; the field is omitted when absent. ' +
+        'Returns { filePath, layer, description?, valid, violations?, autoPatch?, judgmentBrief?, contentHash, ... }.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -2393,6 +2396,9 @@ export async function runArkMcp({ hookInput } = {}) {
   // `allowed:false` denies) — which layers it may and must not import.
   // Q03: when present, attach optional `.ark/golden-pattern.json` (advisory for NEW code only).
   function placeResult(filePath, description) {
+    // Input `description` is the pre-existing "what you are building" hint — not
+    // layers[].description — and must not be copied onto the caption key (ADR 0035 D5).
+    void description;
     const golden = loadGoldenPattern(args.root);
     const withGolden = (placement) => attachGoldenToPlacement(placement, golden);
 
@@ -2433,7 +2439,7 @@ export async function runArkMcp({ hookInput } = {}) {
       filePath,
       layer: layerName,
       governed: true,
-      description: layerMeta?.description,
+      ...placementDescriptionFields(layerMeta),
       forbiddenGlobals: layerMeta?.forbiddenGlobals ?? [],
       ...(layerMeta?.mayImportInfrastructure ? { mayImportInfrastructure: true } : {}),
       mayImport,