@unified-product-graph/core 0.37.0 → 0.39.0

package/CHANGELOG.md

@@ -7,6 +7,46 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.39.0] - 2026-09-04
+
+**A write said "done" while the disk disagreed, and a design system could not point at itself.** Six findings from a second Sanity field brief, written while populating a Studio design layer through roughly two thousand MCP calls across seven graph PRs. One is a correctness bug in the workflow this project's own README recommends; the rest are the design layer's missing vocabulary. Additive throughout.
+
+### Fixed
+
+- **Write tools now return only after the file is written.** `store` saves on a 300ms fire-and-forget debounce, so a successful write returned while the file still held the pre-write state: the documented `batch_*` → read-back → `batch_*` loop raced its own writes, and three field scripts read stale state and worked around it with sleeps. Every mutating tool now awaits the flush at the single dispatcher chokepoint, so the guarantee is structural rather than resting on forty handlers each remembering. A flush failure downgrades the response to an error instead of reporting success over an unwritten file.
+
+### Added
+
+- **`design_token_derives_from_design_token`** (causal, cross-product eligible). The alias tier: primitives (`--gray-100`) that semantic tokens alias (`--background-high: light-dark(var(--gray-100), …)`) that components consume. Measured estate: 163 primitives and 45 aliases whose chain lived in prose. Causal because the alias's value is computed from the primitive's. Makes "which primitives does this component depend on" and "which primitives are dead" traversals.
+- **`feature_area_groups_design_component`** (hierarchy). Component catalogs group by area; 133 components carried an `area:` tag instead. `groups`, not `contains`: the area does not own the component, so this is the non-owning overlay `journey_phase_spans_journey_step` already models.
+- **`validate_graph` reports `property_enum_drift`.** A declared enum was documentation: nothing checked a stored value against it, so an estate wrote `shadow` / `size` / `opacity` into `design_token.category` and saw zero drift, unable to tell whether the enum was strict, extensible, or decorative. Reported, never refused, the `undeclared_property_drift` posture.
+- **`portfolio_validate` reports `registry_file_path_drift`, and `update_product` accepts `file_path`.** A registry entry can point at a path the graph no longer occupies; discovery keeps working because `workspace.json` is authoritative, so nothing surfaced it and nothing repaired it. The report names where the graph actually is; the repair corrects the registry without moving anything, and refuses a path that resolves to nothing.
+
+### Changed
+
+- **`design_component_composes_design_component` is cross-product eligible.** A product graph's shadow component could not point at the design-system primitive it wraps, and eleven wrappers recorded the relationship in descriptions. Widened rather than minting a `_wraps_` twin: a wrap is composition read across a graph boundary, and a second verb for one relationship is a shadow pair.
+- **`design_token.category` speaks the DTCG `$type` vocabulary** alongside its original five values, with the non-one-to-one mapping stated on the property: a `radius` token is a DTCG `dimension`, `motion` is usually a `duration` or `cubicBezier`, `typography` is a composite. Both spellings are accepted, so neither an estate that speaks DTCG nor one that speaks UPG's original five has to translate at the boundary.
+
+Catalog: 1092 → 1094 edges (456 hierarchy · 425 cross-domain · 95 causal · 118 semantic); cross-product 69 → 71. No entity types added or removed.
+
+## [0.38.0] - 2026-09-03
+
+**Cloud-agent hardening: a field brief from a five-repo Cursor Cloud environment found the server fabricating phantom graphs, unverifiable at build time, and unhelpable at setup time.** Seven findings, six accepted (the seventh, filesystem-coupled `code_url` checks, deferred on doctrine); every fix verified live over stdio against the built binaries. Zero catalog/schema surface; minor rather than patch because two behaviors change deliberately.
+
+### Changed (behavior)
+
+- **The mcp-server's empty-resolution fallback dies.** Finding nothing no longer creates a blank `product.upg`: the server REFUSES to start (exit 1), naming the cwd and every path checked. Creation is opt-in via `--init`. In an environment whose cwd you do not control, a silently fabricated graph means every tool call "succeeds" against a phantom and writes are lost with no signal — the refusal is the safe direction, and its message carries the fix.
+- **`upg workspace switch` is session-only.** It writes the gitignored `.upg/workspace.session.json` cursor instead of rewriting the tracked `workspace.json`, so a read-only exploration never leaves a git-backed workspace dirty and an agent's `git add -A` never commits a cursor move. The new `workspace set-default` is the explicit tracked write. The MCP server's `switch_product` always behaved this way; the CLI catches up to the server's own standard.
+
+### Added
+
+- **`--workspace <dir>` / `UPG_WORKSPACE`** on the mcp-server: point at the directory holding the graphs and the server arranges its own cwd (internalizing the shell wrapper cloud environments were hand-writing, the exact layout the field brief verified). `get_workspace_info` and `get_graph_digest` report `workspace_abs_path` so an agent can assert its location.
+- **`upg-mcp-server --check`**: resolves the workspace exactly as the server would, prints `{ok, workspace, resolved_file, products, spec_version, server_version}`, exits 0/1, never starts the transport, never writes. For environment install scripts, so a misconfigured environment fails at build time instead of mid-session. `--help` works (it was an unknown-option error).
+- **`--profile read-only|author`** on the mcp-server: server-side tool-surface filtering applied to `tools/list` AND `tools/call` (the list is discovery, the refusal is the gate), with the profile named in the handshake's server name. Classification fails closed: a new tool is gated out of `read-only` until deliberately classified. `read-only` = the 44 pure reads (plus `switch_product`/`reload_product`; `submit_feedback` excluded, it POSTs externally); `author` gates deletes, migrations, `rename_edge_type`, `push_to_cloud`, `init_workspace`, `create_product`, and the three that delete under another verb.
+- **Spec-version drift warning** at server startup when a graph's sealed `spec_version` is behind the server's (the field case: graphs sealed at 0.8.13 meeting a 0.36.0 server with no signal anywhere).
+- **`--target cursor`** on `upg mcp setup` (writes `.cursor/mcp.json` and prints the team-dashboard snippet cloud agents actually need) and `upg install-skills` (installs the bundled skills into `.cursor/skills/<name>/SKILL.md`).
+- **Deprecated aliases resolve their domain through their replacement** (`getDomainForType`): 36 icon-carrying aliases (`kpi`, `pain_point`, `sla`, `jtbd`, …) rendered tone-neutral in every surface because their names had no domain row while every replacement had one. A rule, not rows — alias rows would make deprecated names look canonical.
+
 ## [0.37.0] - 2026-09-01
 
 **The presentation review: six fields and a widening, one pass over `UPGViewPresentation`.** Every item arrived as measured field evidence from the W2 board charter and the tree-builder investigation (B0, B-1, F-7, F-8), was ruled individually, and lands together so the interface is reviewed once. Additive throughout; every bare pre-0.37.0 form keeps its exact meaning.

package/README.md

@@ -7,7 +7,7 @@
 
 The TypeScript core for the **Unified Product Graph (UPG)**, an open specification that gives product tools a shared vocabulary for entities, edges, and frameworks.
 
-324 entity types across 37 domains. 1092 typed edges. 53 canonical framework definitions, with more added as each is reviewed.
+324 entity types across 37 domains. 1094 typed edges. 53 canonical framework definitions, with more added as each is reviewed.
 
 ## Install