@unified-product-graph/mcp-server 0.9.1 → 0.9.2

package/dist/index.js

@@ -1303,8 +1303,24 @@ var UPG_EDGE_CATALOG = {
   journey_step_realised_by_feature: { forward_verb: "realised_by", reverse_verb: "realises", classification: "cross-domain", source_type: "journey_step", target_type: "feature" },
   opportunity_improves_user_journey: { forward_verb: "improves", reverse_verb: "improved_by", classification: "cross-domain", source_type: "opportunity", target_type: "user_journey" },
   user_journey_passes_through_journey_phase: { forward_verb: "passes_through", reverse_verb: "is_phase_of", classification: "hierarchy", source_type: "user_journey", target_type: "journey_phase" },
-  journey_phase_has_step: { forward_verb: "has_step", reverse_verb: "is_step_in", classification: "hierarchy", source_type: "journey_phase", target_type: "journey_step" },
+  // (since v0.9.2, UPG-663) A journey_phase is a temporal BAND over the
+  // journey's single step timeline, not a container that owns steps. Steps
+  // belong to the journey via `user_journey_contains_journey_step` (the stable
+  // 0.1.0 spine); a phase merely SPANS a range of them. Mirrors the marketing
+  // precedent `customer_journey_stage_spans_journey_step`. Renamed from the
+  // owning `journey_phase_has_step` (hierarchy) so a step has exactly one
+  // containment parent. See UPG_EDGE_MIGRATIONS['0.9.2'].
+  journey_phase_spans_journey_step: { forward_verb: "spans", reverse_verb: "spanned_by", classification: "cross-domain", source_type: "journey_phase", target_type: "journey_step" },
   journey_step_has_action: { forward_verb: "has_action", reverse_verb: "is_action_in", classification: "hierarchy", source_type: "journey_step", target_type: "journey_action" },
+  // (since v0.9.2, UPG-663) journey_action outbound edges. Fixes the
+  // discovery dead-end (D2). The finest blueprint layer carries pain_score /
+  // opportunity_score "to drive opportunity discovery" but previously had zero
+  // outbound edges. Opportunity discovery routes through `need` (mirroring
+  // `journey_step_reveals_need`), which already reaches `opportunity` via the
+  // user chain; the action does not link an opportunity directly. The feature
+  // edge mirrors `journey_step_realised_by_feature` one level deeper.
+  journey_action_surfaces_need: { forward_verb: "surfaces", reverse_verb: "surfaced_in", classification: "cross-domain", source_type: "journey_action", target_type: "need" },
+  journey_action_realised_by_feature: { forward_verb: "realised_by", reverse_verb: "realises", classification: "cross-domain", source_type: "journey_action", target_type: "feature" },
   // 2.5 UI System Domain
   product_systematised_in_design_system: { forward_verb: "systematised_in", reverse_verb: "systematises", classification: "hierarchy", source_type: "product", target_type: "design_system" },
   product_built_with_design_component: { forward_verb: "built_with", reverse_verb: "built_for", classification: "hierarchy", source_type: "product", target_type: "design_component" },
@@ -3029,8 +3045,13 @@ var UPG_VALID_CHILDREN = {
   // parallel to `observation: ['quote']`. Research-synthesis canon.
   // Pairs with `insight_evidenced_by_quote` in the edge catalog.
   // ── Design hierarchy ────────────────────────────────────────────────────────
+  // (UPG-663, v0.9.2) A user_journey owns its steps (the stable 0.1.0 spine)
+  // and carries phases as a non-owning band overlay. A journey_phase is NO
+  // LONGER a containment parent of journey_step: it SPANS steps via the
+  // `journey_phase_spans_journey_step` edge (mirroring the marketing
+  // `customer_journey_stage_spans_journey_step` precedent), so each step has
+  // exactly one containment parent and the journey has one canonical step list.
   user_journey: ["journey_step", "journey_phase"],
-  journey_phase: ["journey_step"],
   journey_step: ["journey_action"],
   // v0.5.8 (UPG-528 Part 2d): insights own their evidencing quotes;
   // parallel to `observation: ['quote']`. Research-synthesis canon
@@ -7127,6 +7148,20 @@ var UPG_SPLIT_MIGRATIONS = {
   ]
 };
 var UPG_EDGE_MIGRATIONS = {
+  "0.9.2": [
+    // (since v0.9.2, UPG-663) Journey-model disambiguation. A journey_phase
+    // is a temporal BAND over the journey's single step timeline, not a
+    // container that owns steps. The owning hierarchy edge
+    // `journey_phase_has_step` is renamed to the non-owning
+    // `journey_phase_spans_journey_step` (mirroring the marketing precedent
+    // `customer_journey_stage_spans_journey_step`). Steps stay owned by the
+    // journey via `user_journey_contains_journey_step` (the stable 0.1.0
+    // spine), so each step keeps a single containment parent and the journey
+    // renders one canonical step list. Endpoints are unchanged
+    // (journey_phase → journey_step); only the edge key and its grammar
+    // (verb has_step → spans, classification hierarchy → cross-domain) change.
+    { kind: "rename", from: "journey_phase_has_step", to: "journey_phase_spans_journey_step", requires_source_type: "journey_phase", requires_target_type: "journey_step", reason: "Journey-model disambiguation (UPG-663): a phase spans steps, it does not own them. The phase to step edge becomes non-owning (verb has_step to spans), so the step keeps a single containment parent (the journey) and the journey has one canonical step list." }
+  ],
   "0.9.0": [
     // (since v0.9.0, UPG-660) theme → roadmap_theme. The four canonical edges that
     // touch the roadmap theme are renamed to the roadmap_theme form. Endpoint guards
@@ -9545,6 +9580,7 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // JourneyActionProperties: Discrete action at a journey step, classified by service layer.
   journey_action: {
+    action_order: { type: "number", description: "Display order of this action within its step (0-indexed). The scalar ordering convention shared with `journey_phase.phase_order` and `journey_step.step_order` (UPG-663). Orders the service-blueprint rows within a single moment." },
     layer: { type: "string", enum: ["user", "frontstage", "backstage", "support"], description: "Service layer" },
     action_description: { type: "string", description: "Plain-language description. Primary content of the action." },
     channel: { type: "string", enum: ["in-app", "email", "web", "mobile", "phone", "in-person", "sms", "social", "other"], description: "Channel or surface. Keeps service-blueprint columns consistent across the journey." },
@@ -9576,7 +9612,7 @@ var UPG_PROPERTY_SCHEMA = {
     system: { type: "string", description: "Performing system or service" },
     notes: { type: "string", description: "Free-text notes, observations, or follow-up questions" }
   },
-  // JourneyPhaseProperties: Phase within a user journey. Groups journey steps into stages.
+  // JourneyPhaseProperties: Phase within a user journey. A temporal BAND over the journey's step
   journey_phase: {
     phase_order: { type: "number", description: "Display order within the journey (0-indexed)" },
     label: { type: "string", description: 'Short human-readable name. @example "Discovery", "Onboarding", "Activation"' },
@@ -9587,8 +9623,9 @@ var UPG_PROPERTY_SCHEMA = {
     key_questions: { type: "string[]", description: "Open questions the user asks themselves. Fuel for design and content priorities." },
     timeframe: { type: "string", description: 'Typical time window. @example "first 30 seconds", "days 1\u20137", "onboarding week"' }
   },
-  // JourneyStepProperties: Single step within a user journey.
+  // JourneyStepProperties: Single step within a user journey. A user-moment on the journey's single
   journey_step: {
+    step_order: { type: "number", description: "Display order within the journey's step timeline (0-indexed). The scalar ordering convention shared with `journey_phase.phase_order` and `journey_action.action_order` (UPG-663). For branching journeys, the explicit `journey_step_precedes_journey_step` edge captures the chain." },
     touchpoint: { type: "string", description: "Interaction touchpoint" },
     channel: { type: "string", description: 'Channel (e.g. "web", "email", "in-store")' },
     emotion_score: {
@@ -17073,8 +17110,13 @@ var STANDARD_LABELS = {
   interview_guide: { alt_labels: ["discussion guide", "interview script", "moderator guide"] },
   survey_response: { alt_labels: ["survey answer", "questionnaire response"] },
   // Design layer
-  user_journey: { alt_labels: ["journey map", "customer journey", "experience map", "journey"] },
-  journey_step: { alt_labels: ["touchpoint", "journey stage", "journey phase"] },
+  // (UPG-663) alt_labels must not collide with other entity types' canonical
+  // names or alt_labels, or the string->type resolver is ambiguous.
+  // Dropped 'customer journey' (collides with customer_journey_stage),
+  // 'touchpoint' and 'journey phase' (both distinct entity surfaces: a
+  // touchpoint is the journey_step.touchpoint property, a phase is journey_phase).
+  user_journey: { alt_labels: ["journey map", "experience map", "journey"] },
+  journey_step: { alt_labels: ["journey moment", "journey stage"] },
   design_component: { alt_labels: ["component", "ui component", "design element"] },
   design_token: { alt_labels: ["token", "style token", "css variable"] },
   wireframe: { alt_labels: ["wireflow", "lo-fi mockup", "skeleton"] },
@@ -19086,7 +19128,11 @@ var PRODUCT_SPEC_GUIDE = {
 var UX_DESIGN_GUIDE = {
   domain_id: "ux_design",
   anchor_entity: "user_journey",
-  creation_sequence: ["user_journey", "journey_phase", "journey_action", "journey_step", "screen", "screen_state", "user_flow", "wireframe", "prototype", "design_question", "design_concept"],
+  // (UPG-663) creation order follows containment: a journey_action is a child
+  // of a journey_step, so the step must precede the action. The journey is the
+  // anchor; phases are the band overlay; steps are the timeline; actions
+  // decompose a step into service-blueprint rows.
+  creation_sequence: ["user_journey", "journey_phase", "journey_step", "journey_action", "screen", "screen_state", "user_flow", "wireframe", "prototype", "design_question", "design_concept"],
   patterns: [
     {
       name: "Journey to Screen Flow",
@@ -22358,6 +22404,40 @@ var UPG_ANTI_PATTERNS = [
     stages: ["concept", "validation", "build", "beta", "launch", "growth", "mature"],
     severity: "medium",
     source: { kind: "fundamental" }
+  },
+  // ── Experience-design layer ─────────────────────────────────────────────
+  {
+    id: "journey-phases-without-canonical-steps",
+    name: "Journey phases without a step spine",
+    description: 'The graph has journey phases spanning steps (`journey_phase_spans_journey_step`), but no journey owns its steps via `user_journey_contains_journey_step`. A phase is a band over a step timeline, not a container. When the timeline itself is missing there is no canonical answer to "what are the steps of this journey?". The phase overlay points at steps the journey does not own.',
+    structured_condition: {
+      operator: "and",
+      checks: [
+        {
+          check: {
+            type: "relationship",
+            source_type: "journey_phase",
+            edge_type: "journey_phase_spans_journey_step",
+            target_type: "journey_step",
+            comparison: "exists"
+          }
+        },
+        {
+          check: {
+            type: "relationship",
+            source_type: "user_journey",
+            edge_type: "user_journey_contains_journey_step",
+            target_type: "journey_step",
+            comparison: "not_exists"
+          }
+        }
+      ]
+    },
+    why_it_matters: "Steps owned by no journey render a different step list per consumer: the phase overlay sees them, a journey-direct walk does not. The journey has no deterministic step spine to traverse, score, or map to screens.",
+    remediation: "Own every step under its journey with `user_journey_contains_journey_step`, then let phases span ranges of that single timeline via `journey_phase_spans_journey_step`. The phase is a non-owning band overlay, not the step container.",
+    stages: ["concept", "validation", "build", "beta", "launch", "growth"],
+    severity: "high",
+    source: { kind: "fundamental" }
   }
 ];
 var SEVERITY_ORDER = {
@@ -24647,7 +24727,7 @@ function serializePortfolioWithHeader(doc, opts) {
   header.integrity = { algorithm: INTEGRITY_ALGORITHM, body: computeBodyChecksum(doc) };
   return JSON.stringify({ $upg: header, ...body }, null, 2) + "\n";
 }
-var UPG_VERSION = "0.9.1";
+var UPG_VERSION = "0.9.2";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
 var UPG_TYPES_SET = new Set(UPG_TYPES);