@unified-product-graph/core 0.9.18 → 0.9.20

package/CHANGELOG.md

@@ -7,6 +7,38 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.9.20] - 2026-06-11
+
+**The tree-pattern catalogue is now introspectable and drift-guarded.** A pattern can no longer cite an edge the grammar lacks, and clients can read the catalogue instead of reverse-engineering it.
+
+### Added
+- **Two introspection tools** (local + cloud, spec-introspection family, local 121 to 123 / cloud 95 to 97):
+  - **`list_tree_patterns`** returns every `get_tree` pattern as a summary row: id, label, the region it is the tree view of, anchor, fallback anchors, natural depth, gap policy, and slot count. Paired with `list_regions`, coverage becomes a queryable diff.
+  - **`get_tree_pattern(id)`** returns the full declarative record: region, anchor, fallbacks, gap policy, depth, and the child map resolved to concrete edges. Each parent-to-child slot carries the canonical `via` edge and its `kind`, resolved live from the edge catalogue, so a client reads the real wiring rather than reverse-engineering it from behaviour.
+- **Declarative pattern records.** `UPGTreePattern` gains `region` (ties a pattern to its region and that region's `shape`) and `gap_policy` (`required-children-only` or `all-optional`). Helpers `listTreePatternSummaries`, `describeTreePattern`, and `resolveTreePatternEdges` expose the catalogue from core.
+- **A drift-guard test.** Every pattern's every `(parent -> child)` slot must resolve to a canonical edge in the catalogue. A pattern that cites an ungrounded pair fails the build. This makes the whole class of bug structural (it already caught an `aggregate -> read_model` slot in the 0.9.19 architecture sketch that the grammar does not wire).
+
+No entity, domain, region, or edge-count change (entities 315, edges 980); local tools 121 to 123, cloud 95 to 97.
+
+---
+
+## [0.9.19] - 2026-06-11
+
+**The tree-pattern catalogue covers every tree-shaped region, and `delivery` finally roots at the roadmap.** `get_tree` now offers 11 patterns (was 8), one per hierarchical region.
+
+### Changed
+- **`delivery` refined.** The 0.9.17 pattern rooted at the product, not the roadmap: its child map listed `product -> roadmap`, which made the product a superset of the roadmap, so the most-nodes anchor rule chose the product even when a roadmap existed. Dropping that slot lets the roadmap win when present; the product is the fallback root (`product -> release`). Added the missing optional children `roadmap_theme -> feature_area`, `release -> changelog`, and `release -> bug`. Default depth is now 3 (a readable overview to the feature tier; `depth` extends into epic and user story).
+
+### Added
+- **Three new tree patterns**, all-optional (browse views, no gap noise):
+  - **`architecture`** (anchor `service`, fallback `bounded_context`): services and the API contracts, endpoints, schemas, queues, deployments, and dependencies they own, grouped by bounded context, with domain aggregates and their members. A DAG: a schema or queue shared by several services renders once, then as a reference.
+  - **`journey`** (anchor `user_journey`, fallback `user_flow`): a journey over time, its phases and steps, the actions within each step, and the screens those steps surface.
+  - **`design_system`** (anchor `design_system`, fallback `design_component`): a design system, its components, their nested sub-components, and the design tokens they consume.
+
+No entity, domain, region, edge, or tool-count change (entities 315, edges 980, local tools 121). The work is in the presentation layer: `UPG_TREE_PATTERNS` (8 to 11) and the pattern lists carried by both servers, the CLI, and the show-tree skill.
+
+---
+
 ## [0.9.18] - 2026-06-11
 
 **The CLI help stops drifting, and an unknown `tree` filter stops lying.** The CLI rendered `--help` from a hand-maintained table divorced from each command's own option definitions, so adding a flag silently left its help stale (that is how `tree --pattern` shipped undocumented in 0.9.17). Separately, `upg tree <unknown>` quietly rendered the whole graph mislabeled as the filter. Both are now structural.

package/dist/index.cjs

@@ -113,6 +113,7 @@ __export(index_exports, {
   collectSlugsForType: () => collectSlugsForType,
   compareVersions: () => compareVersions,
   computeBodyChecksum: () => computeBodyChecksum,
+  describeTreePattern: () => describeTreePattern,
   edgeCarriesProperties: () => edgeCarriesProperties,
   evaluateAntiPatterns: () => evaluateAntiPatterns,
   findInvalidStatusMigrationTargets: () => findInvalidStatusMigrationTargets,
@@ -180,6 +181,7 @@ __export(index_exports, {
   isSubSequenceStep: () => isSubSequenceStep,
   isUPGDocument: () => isUPGDocument,
   listStatusMigrations: () => listStatusMigrations,
+  listTreePatternSummaries: () => listTreePatternSummaries,
   migrateEdge: () => migrateEdge,
   migrateNode: () => migrateNode,
   migrateNodeProperties: () => migrateNodeProperties,
@@ -193,6 +195,7 @@ __export(index_exports, {
   resolveEntityType: () => resolveEntityType,
   resolveLabel: () => resolveLabel,
   resolveSlugCollision: () => resolveSlugCollision,
+  resolveTreePatternEdges: () => resolveTreePatternEdges,
   ringOrderedDomainIds: () => ringOrderedDomainIds,
   rotateSlug: () => rotateSlug,
   serializeCanonical: () => serializeCanonical,
@@ -19879,6 +19882,8 @@ var UPG_TREE_PATTERNS = [
     label: "Opportunity Solution Tree",
     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",
+    region: "discovery_research_validation",
+    gap_policy: "required-children-only",
     anchor_type: "outcome",
     fallback_anchors: ["desired_outcome", "opportunity"],
     child_map: {
@@ -19895,6 +19900,8 @@ var UPG_TREE_PATTERNS = [
     label: "Objectives and Key Results",
     description: "Strategic themes containing objectives, each measured by its key results and the metric that quantifies them (John Doerr).",
     framework_id: "okr-framework",
+    region: "strategy_outcomes",
+    gap_policy: "required-children-only",
     anchor_type: "strategic_theme",
     fallback_anchors: ["objective"],
     child_map: {
@@ -19908,6 +19915,8 @@ var UPG_TREE_PATTERNS = [
     id: "user",
     label: "User chain",
     description: "A persona and the jobs it pursues, branching into the needs and desired outcomes behind them.",
+    region: "users_needs",
+    gap_policy: "required-children-only",
     anchor_type: "persona",
     fallback_anchors: ["job"],
     child_map: {
@@ -19920,6 +19929,8 @@ var UPG_TREE_PATTERNS = [
     id: "product",
     label: "Product breakdown",
     description: "The product organised into feature areas, then features, and the optional epic + user story tiers beneath them.",
+    region: "product_delivery",
+    gap_policy: "required-children-only",
     anchor_type: "product",
     fallback_anchors: ["feature_area", "feature"],
     child_map: {
@@ -19935,6 +19946,8 @@ var UPG_TREE_PATTERNS = [
     label: "Validation chain",
     description: "A hypothesis through its experiment plan, the experiment (or its runs), and the learning it produced.",
     framework_id: "build-measure-learn",
+    region: "discovery_research_validation",
+    gap_policy: "required-children-only",
     anchor_type: "hypothesis",
     fallback_anchors: ["experiment_plan", "experiment"],
     child_map: {
@@ -19949,6 +19962,8 @@ var UPG_TREE_PATTERNS = [
     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 are polymorphically parented: they hang off vision, the product, or a strategic pillar, whichever the graph wired.",
+    region: "strategy_outcomes",
+    gap_policy: "required-children-only",
     anchor_type: "vision",
     fallback_anchors: ["product", "strategic_theme"],
     child_map: {
@@ -19965,6 +19980,8 @@ var UPG_TREE_PATTERNS = [
     id: "feature_areas",
     label: "Feature areas",
     description: "Feature areas and the features they contain.",
+    region: "product_delivery",
+    gap_policy: "all-optional",
     anchor_type: "feature_area",
     fallback_anchors: ["feature"],
     child_map: {
@@ -19975,19 +19992,96 @@ var UPG_TREE_PATTERNS = [
   {
     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.",
+    description: "How product work is scheduled and shipped: the roadmap and its themes/items, the releases they schedule, the features (and the changelog + bugs) those releases deliver, and the feature areas a theme spans. Optional epic + user story tiers appear on request.",
+    region: "product_delivery",
+    gap_policy: "all-optional",
     anchor_type: "roadmap",
-    fallback_anchors: ["product", "release"],
+    // Fallback is the product alone: a graph with no roadmap roots at the
+    // product (product -> release -> feature), reported as anchor_resolved_from:
+    // roadmap. `release` is deliberately NOT a fallback root — a 32-release
+    // forest would out-node the product and shadow it under the most-nodes rule.
+    fallback_anchors: ["product"],
     child_map: {
-      product: [opt("roadmap"), opt("release")],
+      // product holds releases directly (the delivery axis without a roadmap),
+      // but NOT the roadmap: listing roadmap here made the product a superset of
+      // the roadmap, so the most-nodes anchor rule rooted delivery at the product
+      // even when a roadmap existed. Dropping it lets the roadmap win when present.
+      product: [opt("release")],
       roadmap: [opt("roadmap_theme"), opt("roadmap_item"), opt("release")],
-      roadmap_theme: [opt("feature")],
+      roadmap_theme: [opt("feature"), opt("feature_area")],
       roadmap_item: [opt("feature")],
-      release: [opt("feature")],
+      release: [opt("feature"), opt("changelog"), opt("bug")],
       feature: [opt("epic")],
       epic: [opt("user_story")]
     },
-    natural_depth: 5
+    // Default to 3 tiers (roadmap -> theme/item/release -> feature) for a
+    // readable overview on a many-release roadmap; `depth` extends into
+    // epic -> user_story.
+    natural_depth: 3
+  },
+  {
+    id: "architecture",
+    label: "Architecture",
+    description: "The engineering platform: services and the API contracts, endpoints, schemas, queues, deployments, and dependencies they own, grouped by bounded context, with domain aggregates and their members. A DAG (a schema or queue shared by several services renders once, then as a reference).",
+    region: "engineering_platform",
+    gap_policy: "all-optional",
+    anchor_type: "service",
+    fallback_anchors: ["bounded_context"],
+    child_map: {
+      bounded_context: [
+        opt("service"),
+        opt("external_api"),
+        opt("data_flow"),
+        opt("integration_pattern"),
+        opt("code_repository"),
+        opt("api_contract"),
+        opt("aggregate"),
+        opt("domain_event")
+      ],
+      service: [
+        opt("api_contract"),
+        opt("api_endpoint"),
+        opt("database_schema"),
+        opt("queue_topic"),
+        opt("deployment"),
+        opt("build_artifact"),
+        opt("library_dependency"),
+        opt("feature_flag")
+      ],
+      aggregate: [opt("domain_entity"), opt("value_object"), opt("command"), opt("domain_event")]
+    },
+    natural_depth: 3
+  },
+  {
+    id: "journey",
+    label: "User journey",
+    description: "A user journey over time: its phases and steps, the actions within each step, and the screens those steps surface. Falls back to a user_flow when journeys are not yet mapped.",
+    region: "experience_design_brand",
+    gap_policy: "all-optional",
+    anchor_type: "user_journey",
+    fallback_anchors: ["user_flow"],
+    child_map: {
+      user_journey: [opt("journey_phase"), opt("journey_step")],
+      journey_phase: [opt("journey_step")],
+      journey_step: [opt("journey_action"), opt("screen")],
+      user_flow: [opt("screen")],
+      screen: [opt("screen_state")]
+    },
+    natural_depth: 3
+  },
+  {
+    id: "design_system",
+    label: "Design system",
+    description: "A design system broken into its components, their nested sub-components (atom to molecule to organism), and the design tokens they consume.",
+    region: "experience_design_brand",
+    gap_policy: "all-optional",
+    anchor_type: "design_system",
+    fallback_anchors: ["design_component"],
+    child_map: {
+      design_system: [opt("design_component"), opt("design_token")],
+      design_component: [opt("design_component"), opt("design_token")]
+    },
+    natural_depth: 3
   }
 ];
 var UPG_TREE_PATTERNS_BY_ID = Object.fromEntries(
@@ -19996,6 +20090,43 @@ var UPG_TREE_PATTERNS_BY_ID = Object.fromEntries(
 function getTreePattern(id) {
   return UPG_TREE_PATTERNS_BY_ID[id];
 }
+function resolvePatternEdge(source, target) {
+  for (const [id, def] of Object.entries(UPG_EDGE_CATALOG)) {
+    if (def.source_type === source && def.target_type === target) {
+      return { via: id, kind: def.classification };
+    }
+  }
+  return null;
+}
+function resolveTreePatternEdges(pattern) {
+  const out = [];
+  for (const [parent, children] of Object.entries(pattern.child_map)) {
+    for (const c of children) {
+      const e = resolvePatternEdge(parent, c.type);
+      out.push({ parent, child: c.type, via: e?.via ?? null, kind: e?.kind ?? null, required: !!c.required });
+    }
+  }
+  return out;
+}
+function describeTreePattern(id) {
+  const p = getTreePattern(id);
+  if (!p) return void 0;
+  return { ...p, fallback_anchors: [...p.fallback_anchors], edges: resolveTreePatternEdges(p) };
+}
+function listTreePatternSummaries() {
+  return UPG_TREE_PATTERNS.map((p) => ({
+    id: p.id,
+    label: p.label,
+    description: p.description,
+    framework_id: p.framework_id,
+    region: p.region,
+    anchor_type: p.anchor_type,
+    fallback_anchors: [...p.fallback_anchors],
+    natural_depth: p.natural_depth,
+    gap_policy: p.gap_policy,
+    slot_count: Object.values(p.child_map).reduce((n, cs) => n + cs.length, 0)
+  }));
+}
 
 // src/presentation/area-taxonomy.ts
 var UPG_AREA_TAXONOMY = [
@@ -28300,7 +28431,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.9.18";
+var UPG_VERSION = "0.9.20";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -28458,6 +28589,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   collectSlugsForType,
   compareVersions,
   computeBodyChecksum,
+  describeTreePattern,
   edgeCarriesProperties,
   evaluateAntiPatterns,
   findInvalidStatusMigrationTargets,
@@ -28525,6 +28657,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   isSubSequenceStep,
   isUPGDocument,
   listStatusMigrations,
+  listTreePatternSummaries,
   migrateEdge,
   migrateNode,
   migrateNodeProperties,
@@ -28538,6 +28671,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   resolveEntityType,
   resolveLabel,
   resolveSlugCollision,
+  resolveTreePatternEdges,
   ringOrderedDomainIds,
   rotateSlug,
   serializeCanonical,