@unified-product-graph/core 0.17.0 → 0.17.2

package/dist/index.cjs

@@ -98,6 +98,7 @@ __export(index_exports, {
   UPG_MIGRATIONS: () => UPG_MIGRATIONS,
   UPG_PLAYBOOKS: () => UPG_PLAYBOOKS,
   UPG_POLYMORPHIC_EDGE_KEYS: () => UPG_POLYMORPHIC_EDGE_KEYS,
+  UPG_PORTFOLIO_KINDS: () => UPG_PORTFOLIO_KINDS,
   UPG_PRODUCT_STAGES: () => UPG_PRODUCT_STAGES,
   UPG_PRODUCT_STAGE_COERCION_MAP: () => UPG_PRODUCT_STAGE_COERCION_MAP,
   UPG_PROPERTY_MIGRATIONS: () => UPG_PROPERTY_MIGRATIONS,
@@ -2311,6 +2312,16 @@ var UPG_EDGE_CATALOG = {
   // UPG_EDGE_MIGRATIONS['0.9.9'].
   product_organised_into_department: { forward_verb: "organised_into", reverse_verb: "organises", classification: "hierarchy", source_type: "product", target_type: "department" },
   department_contains_team: { forward_verb: "contains", reverse_verb: "belongs_to", classification: "hierarchy", source_type: "department", target_type: "team" },
+  // Second-level team nesting (0.17.2). department_contains_team covers the first
+  // level (department -> team); this covers a team nested inside another team in
+  // the same department (a sub-team or squad under a parent team). Modelled
+  // parent -> child like feature_area_contains_feature_area, so the org map builds
+  // correctly in get_tree (which reads source as the parent); the reverse verb
+  // belongs_to gives the upward "this team is part of that team" read. The
+  // same-department expectation is advisory (a write-time warning), never a hard
+  // block; cross-department reporting lines belong to person_reports_to_person at
+  // the individual level.
+  team_contains_team: { forward_verb: "contains", reverse_verb: "belongs_to", classification: "hierarchy", source_type: "team", target_type: "team" },
   department_includes_stakeholder: { forward_verb: "includes", reverse_verb: "included_in", classification: "hierarchy", source_type: "department", target_type: "stakeholder" },
   // NOTE: `person` is a containment-free entity type (see
   // UPG_CONTAINMENT_FREE_TYPES in grammar/hierarchy.ts). It is referenced
@@ -3420,9 +3431,16 @@ var UPG_CROSS_EDGE_TYPES = [
   "product_implements_design_system",
   // Org-link (0.17.0): dual-registered ownership edges (see UPGCrossEdgeType above).
   "node_owned_by_team",
-  "node_owned_by_department"
+  "node_owned_by_department",
+  // Cross-graph strategy & measurement (0.17.2): dual-registered OKR/measurement
+  // hierarchy edges so the strategy spine can span files (see UPGCrossEdgeType above).
+  "strategic_theme_contains_objective",
+  "objective_achieved_through_key_result",
+  "key_result_quantified_by_metric",
+  "objective_measured_by_metric"
 ];
 var REGISTRY_PRODUCT_ID = "registry";
+var UPG_PORTFOLIO_KINDS = ["owned", "watched", "strategic", "internal", "gtm"];
 
 // src/registry/entity-type-resolution.ts
 var TYPES = getTypes();
@@ -3873,7 +3891,11 @@ var UPG_VALID_CHILDREN = {
     "skill",
     "ceremony",
     "capacity_plan",
-    "decision"
+    "decision",
+    // Self-nesting (0.17.2): a parent team contains its sub-teams / squads, one
+    // level below department_contains_team. Backs team_contains_team. Mirrors
+    // feature_area_contains_feature_area (same-type child listed last).
+    "team"
   ],
   // ── Data & Analytics hierarchy ───────────────────────────────────────────────
   data_source: ["metric", "data_pipeline", "data_lineage", "event_schema"],
@@ -10866,6 +10888,7 @@ var UPG_PROPERTY_SCHEMA = {
   // ConstraintProperties: Constraint: a named limitation or boundary on product creation.
   constraint: {
     constraint_kind: { type: "string", enum: ["resource", "technical", "regulatory", "temporal", "compliance", "other"], description: "Limitation category" },
+    constraint_origin: { type: "string", enum: ["internal", "external"], description: "Provenance: internal (a self-imposed principle or operating tenet) or external (a limit, requirement, or ceiling imposed from outside)." },
     constraint_status: { type: "string", enum: ["binding", "advisory", "lifted"], description: "Whether binding, advisory, or lifted" },
     rule_strength: { type: "string", enum: ["must", "must_not", "exception", "warning", "guideline"], description: "Enforcement strictness. Reuses the governance/guideline rule vocabulary." },
     source: { type: "string", description: "Free-text origin: policy document, regulation, stakeholder, technical doc." },
@@ -23055,7 +23078,8 @@ var STRATEGY_GUIDE = {
   anti_patterns: [
     { description: "Outcomes without metrics. Measurement is the signal an outcome happened." },
     { description: "Objectives without key results: an objective without measurement is a wish" },
-    { description: "Too many strategic themes: focus beats breadth, aim for 2-4 active themes" }
+    { description: "Too many strategic themes: focus beats breadth, aim for 2-4 active themes" },
+    { description: "Constraints without an origin: a qualitative guardrail lives on a constraint, so set constraint_origin to say where it comes from. internal marks a self-imposed principle or operating tenet the team commits to; external marks a limit, requirement, or ceiling imposed from outside (a regulation, a budget cap, a platform bound)." }
   ]
 };
 var PRODUCT_SPEC_GUIDE = {
@@ -23606,6 +23630,12 @@ var TEAM_ORG_GUIDE = {
       description: "Teams are staffed with roles, target OKRs, reflect in retrospectives, and are blocked by dependencies",
       entity_types: ["team", "role", "team_okr", "retrospective", "dependency"],
       edge_chain: ["team_staffed_with_role", "team_targets_team_okr", "team_reflects_in_retrospective", "dependency_blocks_team"]
+    },
+    {
+      name: "Org Nesting",
+      description: "A department contains its teams; a parent team contains its sub-teams or squads one level deeper. Keep a sub-team in the same department as its parent team. Cross-department reporting lines are modelled at the individual level with person_reports_to_person, not by nesting a team under a parent in another department.",
+      entity_types: ["department", "team"],
+      edge_chain: ["department_contains_team", "team_contains_team"]
     }
   ],
   required_bridges: [
@@ -23615,7 +23645,9 @@ var TEAM_ORG_GUIDE = {
   anti_patterns: [
     { description: "Teams without OKRs: every team needs clear goals" },
     { description: "Dependencies without both teams linked: a dependency must connect blocker and blocked" },
-    { description: "Retrospectives without action items: reflection without action is just venting" }
+    { description: "Retrospectives without action items: reflection without action is just venting" },
+    { description: "Nesting a sub-team under a parent team in a different department: a team_contains_team nesting should stay within one department (both teams sharing a department_contains_team parent). A cross-department nesting is almost always a modelling error; model a cross-department reporting line at the individual level with person_reports_to_person instead." },
+    { description: "Double-modelling the org as product_area and team_org: a product_area is the classification axis ON products (which area a product belongs to, the axis used to group products); a team_org department/team is the people structure (the org chart, who reports to whom). Use product_area to classify products and department/team for the org chart, and relate them through the team that owns an area rather than restating one as the other." }
   ]
 };
 var PROGRAM_MGMT_GUIDE = {
@@ -23724,7 +23756,8 @@ var PORTFOLIO_GUIDE = {
   ],
   anti_patterns: [
     { description: "Products without a product area: every product should be classified" },
-    { description: "Portfolios without strategic alignment: portfolio decisions should reflect strategy" }
+    { description: "Portfolios without strategic alignment: portfolio decisions should reflect strategy" },
+    { description: "Confusing product_area with the org chart: product_area is the classification axis on products (how products are grouped), not the people structure. Model who reports to whom with team_org department/team; relate the two through the team that owns an area." }
   ]
 };
 var WORKSPACE_GUIDE = {
@@ -26336,7 +26369,7 @@ var UPG_ANTI_PATTERNS = [
   {
     id: "competitors-missing-past-validation",
     name: "Competitor catalogue empty past validation",
-    description: "The graph has zero competitor entities at validation stage or later. Past concept, the absence of named competitors usually means alternatives haven't been thought through, not that none exist.",
+    description: "The graph has zero competitor entities at build stage or later. Past validation, the absence of named competitors usually means alternatives haven't been thought through, not that none exist. A graph still at concept or validation is exempt: cataloguing the field can wait until you commit to building.",
     structured_condition: {
       check: {
         type: "benchmark",
@@ -26346,14 +26379,18 @@ var UPG_ANTI_PATTERNS = [
     },
     why_it_matters: "Without competitors in the graph, positioning, differentiation, and switching-cost analysis lack referents. The team is reasoning in a vacuum.",
     remediation: "Catalogue the 3\u20135 closest alternatives users would pick today. Use `/upg-compete` to author.",
-    stages: ["validation", "build", "beta", "launch", "growth", "mature"],
+    // Fires from build onward, matching the name (past the validation stage). A
+    // concept or validation graph is still framing the problem; holding it to a
+    // competitor benchmark there is the false alarm this anti-pattern caused on
+    // legitimately-young graphs.
+    stages: ["build", "beta", "launch", "growth", "mature"],
     severity: "medium",
     source: { kind: "industry_practice", category: "product_strategy" }
   },
   {
     id: "persona-count-below-stage-benchmark",
     name: "Persona count below stage benchmark",
-    description: "The graph has fewer personas than the stage-appropriate benchmark expects. Persona under-coverage signals the team has not segmented its audience.",
+    description: "The graph has fewer personas than the stage-appropriate benchmark expects, from beta onward. Persona under-coverage at that point signals the team has not segmented its audience. Concept through build are exempt: the sound move there is to start with one beachhead persona and expand as you find fit.",
     structured_condition: {
       check: {
         type: "benchmark",
@@ -26361,9 +26398,13 @@ var UPG_ANTI_PATTERNS = [
         comparison: "below_min"
       }
     },
-    why_it_matters: 'A graph with one persona past validation is usually carrying an unexamined "everyone is the same user" assumption.',
+    why_it_matters: "A graph still on a single persona by beta is usually carrying an unexamined assumption that every user is the same.",
     remediation: "Add personas representing the next 1\u20132 most distinct user segments. Use `/upg-new-persona`.",
-    stages: ["validation", "build", "beta", "launch", "growth", "mature"],
+    // Fires from beta onward. The persona benchmark expects 2+ from validation,
+    // but the canonical beachhead move is to start with one persona and expand as
+    // fit is found, so holding a build-stage graph to a multi-persona bar is a
+    // false alarm. By beta an unsegmented audience is a real signal.
+    stages: ["beta", "launch", "growth", "mature"],
     severity: "medium",
     source: { kind: "practitioner", attribution: "Alan Cooper, The Inmates Are Running the Asylum" }
   },
@@ -26388,7 +26429,7 @@ var UPG_ANTI_PATTERNS = [
   {
     id: "single-domain-graph",
     name: "Single-domain graph",
-    description: "The graph has more than five entities but they all live in a single UPG domain. A real product spans multiple domains; a single-domain graph is usually a deep notebook in one corner with the rest of the picture missing.",
+    description: "The graph has more than five entities but they all live in a single UPG domain, at beta stage or later. A real product spans multiple domains by then; a single-domain graph that far along is usually a deep notebook in one corner with the rest of the picture missing. Concept through build are exempt: a graph legitimately starts deep in one domain and broadens as it matures.",
     structured_condition: {
       operator: "and",
       checks: [
@@ -26398,7 +26439,11 @@ var UPG_ANTI_PATTERNS = [
     },
     why_it_matters: 'Single-domain coverage prevents cross-domain reasoning. The graph cannot answer questions like "which feature serves which persona?" or "which experiment validates which hypothesis?".',
     remediation: "Identify the next adjacent domain (usually `user`, `validation`, or `product_spec`) and add 2\u20133 anchor entities to bridge.",
-    stages: ["validation", "build", "beta", "launch"],
+    // Fires from beta onward. Early on a graph is legitimately deep in one domain
+    // (a discovery notebook, a thin internal tool); only once it reaches beta is
+    // single-domain coverage a smell rather than a normal starting shape. Extends
+    // through growth and mature, where a single-domain graph is most telling.
+    stages: ["beta", "launch", "growth", "mature"],
     severity: "medium",
     source: { kind: "fundamental" }
   },
@@ -29796,7 +29841,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.17.0";
+var UPG_VERSION = "0.17.2";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -29929,6 +29974,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   UPG_MIGRATIONS,
   UPG_PLAYBOOKS,
   UPG_POLYMORPHIC_EDGE_KEYS,
+  UPG_PORTFOLIO_KINDS,
   UPG_PRODUCT_STAGES,
   UPG_PRODUCT_STAGE_COERCION_MAP,
   UPG_PROPERTY_MIGRATIONS,