arkgate 4.8.6 → 4.8.7

package/CHANGELOG.md

@@ -3,16 +3,39 @@
 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. Do not npm-publish from this item until
-the maintainer tag.
+`K01` / `Z09`. No `/ark-order` skill.
 
-**Status: prepared** (tree ready; npm `latest` remains **4.8.5** until publish).
+**Status: published** (on npm `latest`; see `docs/releases/4.8.6.md`).
 
 ### Added
 - **`apply(ProposeResult)`** on `createOrderPlane`. Unvalved second freeze of a
@@ -42,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: published** (on npm `latest`; see `docs/releases/4.8.5.md`).
+**Status: published** (see `docs/releases/4.8.5.md`).
 
 ### Added
 - **`docs/arkorder.md`:** named APIs adopters were redesigning (`createOrderPlane`,

package/README.md

@@ -29,7 +29,7 @@ Works with Cursor, Claude, Codex, and Grok.
 
 </div>
 
-> **ArkGate 4.8.5** is on npm `latest`. This tree is **4.8.6** (prepared patch; not published).
+> **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**
@@ -309,8 +309,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) |
-| 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) |
+| 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) |

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,