@unified-product-graph/core 0.9.15 → 0.9.17

package/CHANGELOG.md

@@ -7,6 +7,38 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.9.17] - 2026-06-11
+
+**CLI-next: the CLI catches up to the spec, the tree learns its frameworks, and ordering finally means something.** The `upg` CLI had frozen at the 0.8.x command set while the MCP tool surface grew to 121; its `list`/`tree` ordered lexically and re-rendered shared subtrees into noise. This release closes all of it, and folds in the `get_tree` pattern-definition fixes from a post-ship report on a real 304-node graph.
+
+### Added
+- **Meaning-aware node ordering** (`compareNodesWithinType`, SDK). The intra-type sort ladder: explicit order field (`<type>_order` / order / sequence / ...) -> semantic version (title or `version`) -> lifecycle/status phase position -> `created_at` -> numeric-aware locale. A release series now reads `v5.0.0, v5.1.0, ... v5.9.0, v5.10.0, ... v5.30.0, v6.0.0` instead of the lexical `v5.1.0, v5.10.0, ... v5.2.0`. `list`/`tree` and `get_tree` share it.
+- **DAG-honest tree assembly.** A UPG graph is a DAG; a multi-parent node now renders its subtree ONCE and appears as a `shared` reference under its other parents, in both `get_tree` (`stats.shared_refs`) and the CLI `tree` (`↗ shown above`). Nothing is silently dropped, nothing re-explodes, cycles terminate. `assembleTree` moved to the SDK so the local server, cloud server, and CLI share one implementation.
+- **A `delivery` tree pattern** for the roadmap/release region; `UPG_TREE_PATTERNS` is now 8.
+- **CLI tool-parity surface**: the full 0.9.x MCP surface as commands. New groups `spec` (offline catalogue browser, 36 nouns), `query`, `registry`, `portfolio`, `area`, `migrate`; `tree --pattern <id>` (framework-aware trees via the shared assembler); and singletons `move`, `disconnect`, `dedupe`, `clone`, `context`, `log`, `prioritise`, `sync status`, `product update`, `batch`. Six MCP tools are deliberately not mirrored (recorded by ADR): the agent-cognitive `plan`/`reflect`/`trace`, the remote-mutating `apply_pull_changeset`/`push_to_cloud`, and the skill-dev `skill_audit`.
+
+### Changed
+- **`get_tree` pattern definitions corrected (G1-G7)** against the real graph: child slots gain a `required` flag so gaps flag only genuinely-missing required children (no more ~50 false `epic` gaps); the `strategy` pattern reaches the polymorphically-parented bets and auto-flags a bet with no initiative; `okr` extends to the `metric` leaf and `ost` to `hypothesis`/`experiment_plan`; `validation` accepts `experiment` or `experiment_run`; anchor selection picks the candidate that surfaces the most of the pattern, not the first non-empty.
+
+No entity, domain, region, playbook, framework, or local-tool count change (entities 315, edges 980, local tools 121, regions 11, frameworks 46). The work is in the CLI, the SDK, and the tree presentation layer.
+
+---
+
+## [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.

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,
@@ -121,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,
@@ -18403,13 +18408,13 @@ function validateFrameworkScores(nodes, edges, warnings) {
     const divisors = divisorInputs(framework);
     const path = `$.edges[${i}].properties`;
     const scoreObj = score;
-    for (const req of requirements) {
-      const value = scoreObj[req.property];
+    for (const req2 of requirements) {
+      const value = scoreObj[req2.property];
       if (value === void 0 || value === null) continue;
-      const finding = checkScoreValue(req, value, divisors.has(req.property), framework.id);
+      const finding = checkScoreValue(req2, value, divisors.has(req2.property), framework.id);
       if (finding) {
         warnings.push({
-          path: `${path}.${req.property}`,
+          path: `${path}.${req2.property}`,
           message: finding,
           rule: "framework-score"
         });
@@ -18429,58 +18434,58 @@ function divisorInputs(framework) {
   return out;
 }
 var EMPTY_STRING_SET = /* @__PURE__ */ new Set();
-function checkScoreValue(req, value, isDivisor, frameworkId) {
-  switch (req.type) {
+function checkScoreValue(req2, value, isDivisor, frameworkId) {
+  switch (req2.type) {
     case "enum": {
-      const allowed = req.enum_values ?? [];
+      const allowed = req2.enum_values ?? [];
       if (typeof value !== "string") {
-        return `${frameworkId} score "${req.property}" must be one of ${allowed.join(", ")}; got ${describeKind(value)}.`;
+        return `${frameworkId} score "${req2.property}" must be one of ${allowed.join(", ")}; got ${describeKind(value)}.`;
       }
       if (allowed.length > 0 && !allowed.includes(value)) {
-        return `${frameworkId} score "${req.property}" has value "${value}" outside its allowed set: ${allowed.join(", ")}.`;
+        return `${frameworkId} score "${req2.property}" has value "${value}" outside its allowed set: ${allowed.join(", ")}.`;
       }
       return null;
     }
     case "assessment": {
       const num = numericScore(value);
       if (num === null) {
-        return `${frameworkId} score "${req.property}" must be a number; got ${describeKind(value)}.`;
+        return `${frameworkId} score "${req2.property}" must be a number; got ${describeKind(value)}.`;
       }
-      const scale = req.scale_id ? getScale(req.scale_id) : void 0;
+      const scale = req2.scale_id ? getScale(req2.scale_id) : void 0;
       if (scale) {
         if (num < scale.min || num > scale.max) {
-          return `${frameworkId} score "${req.property}" is ${num}, outside the ${req.scale_id} scale range [${scale.min}, ${scale.max}].`;
+          return `${frameworkId} score "${req2.property}" is ${num}, outside the ${req2.scale_id} scale range [${scale.min}, ${scale.max}].`;
         }
       } else if (num <= 0) {
-        return `${frameworkId} score "${req.property}" must be greater than 0; got ${num}.`;
+        return `${frameworkId} score "${req2.property}" must be greater than 0; got ${num}.`;
       }
       if (isDivisor && num === 0) {
-        return `${frameworkId} score "${req.property}" must not be 0 (it is a divisor in the framework's formula).`;
+        return `${frameworkId} score "${req2.property}" must not be 0 (it is a divisor in the framework's formula).`;
       }
       return null;
     }
     case "number": {
       const num = numericScore(value);
       if (num === null) {
-        return `${frameworkId} score "${req.property}" must be a number; got ${describeKind(value)}.`;
+        return `${frameworkId} score "${req2.property}" must be a number; got ${describeKind(value)}.`;
       }
       if (isDivisor && num === 0) {
-        return `${frameworkId} score "${req.property}" must not be 0 (it is a divisor in the framework's formula).`;
+        return `${frameworkId} score "${req2.property}" must not be 0 (it is a divisor in the framework's formula).`;
       }
       if (num < 0) {
-        return `${frameworkId} score "${req.property}" must not be negative; got ${num}.`;
+        return `${frameworkId} score "${req2.property}" must not be negative; got ${num}.`;
       }
       return null;
     }
     case "boolean": {
       if (typeof value !== "boolean") {
-        return `${frameworkId} score "${req.property}" must be a boolean; got ${describeKind(value)}.`;
+        return `${frameworkId} score "${req2.property}" must be a boolean; got ${describeKind(value)}.`;
       }
       return null;
     }
     case "string": {
       if (typeof value !== "string") {
-        return `${frameworkId} score "${req.property}" must be a string; got ${describeKind(value)}.`;
+        return `${frameworkId} score "${req2.property}" must be a string; got ${describeKind(value)}.`;
       }
       return null;
     }
@@ -19866,33 +19871,38 @@ function buildTypeAliases() {
 var UPG_TYPE_ALIASES = buildTypeAliases();
 
 // src/presentation/tree-patterns.ts
+var req = (type) => ({ type, required: true });
+var opt = (type) => ({ type });
 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).",
+    description: "A desired outcome branching into the opportunities under it, the solutions that address them, and the hypotheses + experiment plans that validate 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"]
+      outcome: [req("opportunity")],
+      desired_outcome: [req("opportunity")],
+      opportunity: [req("solution")],
+      solution: [opt("hypothesis")],
+      hypothesis: [opt("experiment_plan")]
     },
-    natural_depth: 3
+    natural_depth: 5
   },
   {
     id: "okr",
     label: "Objectives and Key Results",
-    description: "Strategic themes containing objectives, each measured by its key results (John Doerr).",
+    description: "Strategic themes containing objectives, each measured by its key results and the metric that quantifies them (John Doerr).",
     framework_id: "okr-framework",
     anchor_type: "strategic_theme",
     fallback_anchors: ["objective"],
     child_map: {
-      strategic_theme: ["objective"],
-      objective: ["key_result"]
+      strategic_theme: [req("objective")],
+      objective: [req("key_result")],
+      key_result: [opt("metric")]
     },
-    natural_depth: 3
+    natural_depth: 4
   },
   {
     id: "user",
@@ -19901,54 +19911,55 @@ var UPG_TREE_PATTERNS = [
     anchor_type: "persona",
     fallback_anchors: ["job"],
     child_map: {
-      persona: ["job", "need", "desired_outcome"],
-      job: ["need", "desired_outcome"]
+      persona: [req("job"), opt("need"), opt("desired_outcome")],
+      job: [opt("need"), opt("desired_outcome")]
     },
     natural_depth: 3
   },
   {
     id: "product",
     label: "Product breakdown",
-    description: "The product organised into feature areas, then features, epics, and user stories.",
+    description: "The product organised into feature areas, then features, and the optional epic + user story tiers beneath them.",
     anchor_type: "product",
     fallback_anchors: ["feature_area", "feature"],
     child_map: {
-      product: ["feature_area"],
-      feature_area: ["feature"],
-      feature: ["epic"],
-      epic: ["user_story"]
+      product: [opt("feature_area")],
+      feature_area: [req("feature")],
+      feature: [opt("epic")],
+      epic: [opt("user_story")]
     },
     natural_depth: 5
   },
   {
     id: "validation",
     label: "Validation chain",
-    description: "A hypothesis through its experiment plan, experiment, run, and the learning it produced.",
+    description: "A hypothesis through its experiment plan, the experiment (or its runs), 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"]
+      hypothesis: [req("experiment_plan")],
+      experiment_plan: [req("experiment"), req("experiment_run")],
+      experiment: [opt("experiment_run"), opt("learning")],
+      experiment_run: [opt("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.",
+    description: "Vision and mission into the strategic themes (bets), the initiatives that pursue them, and the outcomes they drive. Themes are polymorphically parented: they hang off vision, the product, or a strategic pillar, 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"]
+      vision: [opt("mission"), opt("strategic_theme")],
+      mission: [opt("strategic_pillar")],
+      strategic_pillar: [opt("strategic_theme")],
+      product: [opt("strategic_theme")],
+      strategic_theme: [req("initiative")],
+      initiative: [opt("outcome")]
     },
-    natural_depth: 4
+    natural_depth: 5
   },
   {
     id: "feature_areas",
@@ -19957,9 +19968,26 @@ var UPG_TREE_PATTERNS = [
     anchor_type: "feature_area",
     fallback_anchors: ["feature"],
     child_map: {
-      feature_area: ["feature"]
+      feature_area: [opt("feature")]
     },
     natural_depth: 2
+  },
+  {
+    id: "delivery",
+    label: "Delivery roadmap",
+    description: "How product work is scheduled and shipped: the roadmap and its themes/items, the releases they schedule, and the features (with optional epic + user story tiers) they deliver.",
+    anchor_type: "roadmap",
+    fallback_anchors: ["product", "release"],
+    child_map: {
+      product: [opt("roadmap"), opt("release")],
+      roadmap: [opt("roadmap_theme"), opt("roadmap_item"), opt("release")],
+      roadmap_theme: [opt("feature")],
+      roadmap_item: [opt("feature")],
+      release: [opt("feature")],
+      feature: [opt("epic")],
+      epic: [opt("user_story")]
+    },
+    natural_depth: 5
   }
 ];
 var UPG_TREE_PATTERNS_BY_ID = Object.fromEntries(
@@ -19969,6 +19997,36 @@ 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 {
@@ -28242,7 +28300,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.9.15";
+var UPG_VERSION = "0.9.17";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -28331,6 +28389,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,
@@ -28408,9 +28468,12 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   getAntiPatterns,
   getAntiPatternsBySeverity,
   getAntiPatternsForStage,
+  getAreaTaxonomyEntry,
   getBenchmark,
   getBenchmarksByDomain,
+  getBusinessAreasForRegion,
   getCanonicalPlaybookForRegion,
+  getCoverageKeysForRegion,
   getDefaultLens,
   getDeprecatedTypes,
   getDomainForType,