@unified-product-graph/core 0.9.14 → 0.9.16

package/CHANGELOG.md

@@ -7,6 +7,37 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.9.16] - 2026-06-11
+
+**get_tree reaches the cloud, the show-tree skill calls it, and the three "area" taxonomies get a documented cross-walk.** 0.9.15 shipped `get_tree` local-only and left the show-tree skill on its interim hardcoded chains; this release finishes the loop and closes the deferred A4 introspection gap.
+
+### Added
+- **`get_tree` on the cloud server** (cloud tools 94 to 95; local unchanged at 121). The assembler (`assembleTree` + the `GraphReader` interface) moved to the shared `@unified-product-graph/mcp-tooling` package, so the local file-backed server and the cloud Postgres-backed server assemble byte-identical trees from one source. The cloud handler builds an in-memory `GraphReader` from a one-shot product node+edge load. `get_tree` leaves the CLOUD_NA parity list.
+- **`UPG_AREA_TAXONOMY`** (core): the documented cross-walk between the three overlapping "area" groupings that skills kept conflating into a stale coverage denominator: the 10 `get_graph_digest.coverage` keys, the 11 canonical regions, and the 8 "business areas". Keyed by coverage key; each row names the matching business area (null for `validation` and `operations`, which the 8-area grouping folds into discovery / omits) and the region ids its entities live in. Helpers `getCoverageKeysForRegion` / `getBusinessAreasForRegion`. Surfaced on `list_regions` (an `area_taxonomy` block plus per-region `coverage_keys` / `business_areas`) and `get_region` (per-region `coverage_keys` / `business_areas`), local and cloud. An SDK drift test pins the key sets against the runtime sources (`BUSINESS_AREAS`, `BUSINESS_AREA_META`).
+
+### Changed
+- **`/upg-show-tree` calls `get_tree`** instead of building traverse chains and resolving edge names. The skill now renders the returned roots / children, surfaces `gaps`, and notes anchor fallback; it no longer carries the edge-name chains that drifted (the exact failure `get_tree` exists to prevent). Adds the `feature_areas` pattern. Skills ship in the mcp-server package, so this reaches users with the release.
+
+No entity, domain, region, playbook, framework, or edge-count change, and no change to the local tool surface (entities 315, edges 980, local tools 121, regions 11).
+
+---
+
+## [0.9.15] - 2026-06-11
+
+**get_tree: server-side tree assembly.** Tree views (OST, OKR, user, product, validation, strategy, feature areas) were assembled client-side by the show-tree skill out of multiple query calls and hardcoded edge chains that drifted with the spec. This release relocates assembly to the server, which owns the catalogue.
+
+### Added
+- **`UPG_TREE_PATTERNS`** (core): 7 canonical tree patterns, each an anchor type + a TYPE-DRIVEN `child_map` (parent type to allowed child types), not a list of edge names. A pattern follows the live graph to a neighbour of the next expected type, whatever edge wired them, so a chain refinement in the edge catalogue cannot rot it (the failure mode that drifted the skill's hardcoded chains). Chains authored by resolving every pair against the live catalogue.
+- **`get_tree`** (tools 120 to 121, local only): assembles a pattern from the active product graph and returns NESTED data plus structural `gaps` (a node whose pattern expects children the graph lacks: a bet with no initiative, an objective with no key result). Roots at the pattern anchor, falling back through `fallback_anchors` when the anchor has no nodes or reaches nothing (the "wrong root, empty tree" case), and reports the substitution (`anchor_resolved_from` / `anchor_used`). `max_nodes` summarises rather than silently truncating. Rendering (emoji, ASCII) stays in the client; the tool composes with `query` rather than replacing it.
+
+### Notes
+- `query.traverse` is unchanged: its set-vs-positional semantics is a separate concern, and flipping it would break path-walk callers, so `get_tree` encapsulates the branching multi-pass internally instead.
+- A cloud-server parallel of `get_tree` is a follow-up (it needs a Postgres-store traversal); v1 is local, where the primary consumer (the show-tree skill) runs.
+
+No entity, domain, region, playbook, framework, or edge-count change (entities 315, edges 980, tools 121).
+
+---
+
 ## [0.9.14] - 2026-06-11
 
 **Introspection completeness: make the live surface complete and honest so clients can stop hardcoding.** A diagnostic of the skill suite found shared docs pointing skills at an introspection field that did not exist, two redundant status fields, a silent mis-parenting path, and four expected frameworks that hard-errored. This release closes those gaps.

package/dist/index.cjs

@@ -44,6 +44,8 @@ __export(index_exports, {
   UPG_ANTI_PATTERNS: () => UPG_ANTI_PATTERNS,
   UPG_APPROACHES: () => UPG_APPROACHES,
   UPG_APPROACHES_BY_ID: () => UPG_APPROACHES_BY_ID,
+  UPG_AREA_TAXONOMY: () => UPG_AREA_TAXONOMY,
+  UPG_AREA_TAXONOMY_BY_COVERAGE_KEY: () => UPG_AREA_TAXONOMY_BY_COVERAGE_KEY,
   UPG_CANONICAL_FORMAT_VERSION: () => UPG_CANONICAL_FORMAT_VERSION,
   UPG_CONTAINMENT_FREE_TYPES: () => UPG_CONTAINMENT_FREE_TYPES,
   UPG_COUNT_BENCHMARKS: () => UPG_COUNT_BENCHMARKS,
@@ -91,6 +93,8 @@ __export(index_exports, {
   UPG_SPLIT_MIGRATIONS: () => UPG_SPLIT_MIGRATIONS,
   UPG_STATUS_MIGRATIONS: () => UPG_STATUS_MIGRATIONS,
   UPG_STRUCTURE_PATTERNS: () => UPG_STRUCTURE_PATTERNS,
+  UPG_TREE_PATTERNS: () => UPG_TREE_PATTERNS,
+  UPG_TREE_PATTERNS_BY_ID: () => UPG_TREE_PATTERNS_BY_ID,
   UPG_TYPES: () => UPG_TYPES,
   UPG_TYPES_SET: () => UPG_TYPES_SET,
   UPG_TYPE_ALIASES: () => UPG_TYPE_ALIASES,
@@ -119,9 +123,12 @@ __export(index_exports, {
   getAntiPatterns: () => getAntiPatterns,
   getAntiPatternsBySeverity: () => getAntiPatternsBySeverity,
   getAntiPatternsForStage: () => getAntiPatternsForStage,
+  getAreaTaxonomyEntry: () => getAreaTaxonomyEntry,
   getBenchmark: () => getBenchmark,
   getBenchmarksByDomain: () => getBenchmarksByDomain,
+  getBusinessAreasForRegion: () => getBusinessAreasForRegion,
   getCanonicalPlaybookForRegion: () => getCanonicalPlaybookForRegion,
+  getCoverageKeysForRegion: () => getCoverageKeysForRegion,
   getDefaultLens: () => getDefaultLens,
   getDeprecatedTypes: () => getDeprecatedTypes,
   getDomainForType: () => getDomainForType,
@@ -149,6 +156,7 @@ __export(index_exports, {
   getRingForDomain: () => getRingForDomain,
   getScale: () => getScale,
   getSplitMigrations: () => getSplitMigrations,
+  getTreePattern: () => getTreePattern,
   getTypeId: () => getTypeId,
   getTypeName: () => getTypeName,
   getTypes: () => getTypes,
@@ -19862,6 +19870,140 @@ function buildTypeAliases() {
 }
 var UPG_TYPE_ALIASES = buildTypeAliases();
 
+// src/presentation/tree-patterns.ts
+var UPG_TREE_PATTERNS = [
+  {
+    id: "ost",
+    label: "Opportunity Solution Tree",
+    description: "A desired outcome branching into the opportunities under it and the solutions that address them (Teresa Torres).",
+    framework_id: "opportunity-solution-tree",
+    anchor_type: "outcome",
+    fallback_anchors: ["desired_outcome", "opportunity"],
+    child_map: {
+      outcome: ["opportunity"],
+      desired_outcome: ["opportunity"],
+      opportunity: ["solution"]
+    },
+    natural_depth: 3
+  },
+  {
+    id: "okr",
+    label: "Objectives and Key Results",
+    description: "Strategic themes containing objectives, each measured by its key results (John Doerr).",
+    framework_id: "okr-framework",
+    anchor_type: "strategic_theme",
+    fallback_anchors: ["objective"],
+    child_map: {
+      strategic_theme: ["objective"],
+      objective: ["key_result"]
+    },
+    natural_depth: 3
+  },
+  {
+    id: "user",
+    label: "User chain",
+    description: "A persona and the jobs it pursues, branching into the needs and desired outcomes behind them.",
+    anchor_type: "persona",
+    fallback_anchors: ["job"],
+    child_map: {
+      persona: ["job", "need", "desired_outcome"],
+      job: ["need", "desired_outcome"]
+    },
+    natural_depth: 3
+  },
+  {
+    id: "product",
+    label: "Product breakdown",
+    description: "The product organised into feature areas, then features, epics, and user stories.",
+    anchor_type: "product",
+    fallback_anchors: ["feature_area", "feature"],
+    child_map: {
+      product: ["feature_area"],
+      feature_area: ["feature"],
+      feature: ["epic"],
+      epic: ["user_story"]
+    },
+    natural_depth: 5
+  },
+  {
+    id: "validation",
+    label: "Validation chain",
+    description: "A hypothesis through its experiment plan, experiment, run, and the learning it produced.",
+    framework_id: "build-measure-learn",
+    anchor_type: "hypothesis",
+    fallback_anchors: ["experiment_plan", "experiment"],
+    child_map: {
+      hypothesis: ["experiment_plan"],
+      experiment_plan: ["experiment"],
+      experiment: ["experiment_run"],
+      experiment_run: ["learning"]
+    },
+    natural_depth: 5
+  },
+  {
+    id: "strategy",
+    label: "Strategy cascade",
+    description: "Vision and mission into the strategic themes (bets), the initiatives that pursue them, and the outcomes they drive. Themes anchor on vision OR the product, whichever the graph wired.",
+    anchor_type: "vision",
+    fallback_anchors: ["product", "strategic_theme"],
+    child_map: {
+      vision: ["mission", "strategic_theme"],
+      product: ["strategic_theme"],
+      mission: ["strategic_theme"],
+      strategic_theme: ["initiative"],
+      initiative: ["outcome"]
+    },
+    natural_depth: 4
+  },
+  {
+    id: "feature_areas",
+    label: "Feature areas",
+    description: "Feature areas and the features they contain.",
+    anchor_type: "feature_area",
+    fallback_anchors: ["feature"],
+    child_map: {
+      feature_area: ["feature"]
+    },
+    natural_depth: 2
+  }
+];
+var UPG_TREE_PATTERNS_BY_ID = Object.fromEntries(
+  UPG_TREE_PATTERNS.map((p) => [p.id, p])
+);
+function getTreePattern(id) {
+  return UPG_TREE_PATTERNS_BY_ID[id];
+}
+
+// src/presentation/area-taxonomy.ts
+var UPG_AREA_TAXONOMY = [
+  { coverage_key: "identity", label: "Identity", business_area: "identity", regions: ["strategy_outcomes"] },
+  { coverage_key: "understanding", label: "Understanding", business_area: "understanding", regions: ["users_needs", "discovery_research_validation"] },
+  { coverage_key: "discovery", label: "Discovery", business_area: "discovery", regions: ["discovery_research_validation", "market_competitive"] },
+  { coverage_key: "validation", label: "Validation", business_area: null, regions: ["discovery_research_validation"] },
+  { coverage_key: "reaching", label: "Reaching", business_area: "reaching", regions: ["business_gtm_growth"] },
+  { coverage_key: "converting", label: "Converting", business_area: "converting", regions: ["business_gtm_growth"] },
+  { coverage_key: "building", label: "Building", business_area: "building", regions: ["product_delivery", "experience_design_brand"] },
+  { coverage_key: "sustaining", label: "Sustaining", business_area: "sustaining", regions: ["business_gtm_growth"] },
+  { coverage_key: "learning", label: "Learning", business_area: "learning", regions: ["strategy_outcomes", "analytics_data", "operations_quality"] },
+  { coverage_key: "operations", label: "Operations", business_area: null, regions: ["operations_quality"] }
+];
+var UPG_AREA_TAXONOMY_BY_COVERAGE_KEY = Object.fromEntries(UPG_AREA_TAXONOMY.map((e) => [e.coverage_key, e]));
+function getAreaTaxonomyEntry(coverageKey) {
+  return UPG_AREA_TAXONOMY_BY_COVERAGE_KEY[coverageKey];
+}
+function getCoverageKeysForRegion(regionId) {
+  return UPG_AREA_TAXONOMY.filter((e) => e.regions.includes(regionId)).map((e) => e.coverage_key);
+}
+function getBusinessAreasForRegion(regionId) {
+  const out = [];
+  for (const e of UPG_AREA_TAXONOMY) {
+    if (e.regions.includes(regionId) && e.business_area && !out.includes(e.business_area)) {
+      out.push(e.business_area);
+    }
+  }
+  return out;
+}
+
 // src/playbooks/definitions/index.ts
 function seqStep(order, phase, entity_types, prompt_hint, options) {
   return {
@@ -28135,7 +28277,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.9.14";
+var UPG_VERSION = "0.9.16";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -28224,6 +28366,8 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   UPG_ANTI_PATTERNS,
   UPG_APPROACHES,
   UPG_APPROACHES_BY_ID,
+  UPG_AREA_TAXONOMY,
+  UPG_AREA_TAXONOMY_BY_COVERAGE_KEY,
   UPG_CANONICAL_FORMAT_VERSION,
   UPG_CONTAINMENT_FREE_TYPES,
   UPG_COUNT_BENCHMARKS,
@@ -28271,6 +28415,8 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   UPG_SPLIT_MIGRATIONS,
   UPG_STATUS_MIGRATIONS,
   UPG_STRUCTURE_PATTERNS,
+  UPG_TREE_PATTERNS,
+  UPG_TREE_PATTERNS_BY_ID,
   UPG_TYPES,
   UPG_TYPES_SET,
   UPG_TYPE_ALIASES,
@@ -28299,9 +28445,12 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   getAntiPatterns,
   getAntiPatternsBySeverity,
   getAntiPatternsForStage,
+  getAreaTaxonomyEntry,
   getBenchmark,
   getBenchmarksByDomain,
+  getBusinessAreasForRegion,
   getCanonicalPlaybookForRegion,
+  getCoverageKeysForRegion,
   getDefaultLens,
   getDeprecatedTypes,
   getDomainForType,
@@ -28329,6 +28478,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   getRingForDomain,
   getScale,
   getSplitMigrations,
+  getTreePattern,
   getTypeId,
   getTypeName,
   getTypes,