@unified-product-graph/core 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -7,7 +7,44 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
-## [0.9.0] - Unreleased
+## [0.9.2] - 2026-06-09
+
+**Journey-model disambiguation (UPG-663).** The four Experience-Design journey types (`user_journey`, `journey_phase`, `journey_step`, `journey_action`) had a coherent concept but broken wiring: there was no deterministic answer to "what are the steps of this journey?". A `journey_phase` is now a temporal band that **spans** steps, not a container that **owns** them, mirroring the marketing precedent `customer_journey_stage_spans_journey_step`. Steps stay owned by `user_journey` (the stable 0.1.0 spine), so each step has exactly one containment parent and the journey renders one canonical step list. Additive plus one edge rename (dual-read via `UPG_EDGE_MIGRATIONS['0.9.2']`). Decision: `2026-06-09-journey-model-disambiguation.md`.
+
+### Added
+- `journey_action_surfaces_need` and `journey_action_realised_by_feature` edges: `journey_action` previously had zero outbound edges despite carrying `pain_score` / `opportunity_score` "to drive opportunity discovery". Opportunity discovery now routes through `need` (which reaches `opportunity` via `opportunity_addresses_need`), mirroring `journey_step_reveals_need` one level deeper.
+- `JourneyStepProperties.step_order` and `JourneyActionProperties.action_order`: scalar ordering, completing a single `*_order` convention across phase / step / action (matching the existing `phase_order` and `customer_journey_stage.stage_order`). `journey_step_precedes_journey_step` remains the explicit-chain option for branching journeys.
+- `journey-phases-without-canonical-steps` curated anti-pattern (high severity): fires when phases span steps but no journey owns them via `user_journey_contains_journey_step`, so `validate_graph` surfaces a journey with no canonical step spine.
+
+### Changed
+- **`journey_phase_has_step` → `journey_phase_spans_journey_step`** (paired, via `UPG_EDGE_MIGRATIONS['0.9.2']`): the phase-to-step edge becomes non-owning (verb `has_step` to `spans`, classification `hierarchy` to `cross-domain`). `journey_phase` is removed as a containment parent of `journey_step` in the hierarchy; `user_journey` keeps `journey_step` (owned spine) and `journey_phase` (band overlay).
+- `properties/domains/ux-design.ts` JSDoc reconciled to the actual edge names (removed six phantom edges that the spec documented but never shipped).
+- `presentation/labels.ts` alt-label collisions removed: `user_journey` drops `"customer journey"` (collided with `customer_journey_stage`); `journey_step` drops `"touchpoint"` and `"journey phase"` (distinct entity surfaces).
+- `intelligence/domain-guides.ts` UX creation sequence reordered so `journey_step` precedes its child `journey_action`.
+
+### Notes
+- `journey_phase` and `journey_action` remain `proposed` (the v0.2 Experience-Design extension over the stable 0.1.0 journey/step spine); not promoted to `stable` in this pass.
+
+---
+
+## [0.9.1] - 2026-06-09
+
+**Cross-product read layer + an OKR-alignment edge + a workspace-resolution fix.** One core spec addition (the `contributes_to` cross-product edge), the read counterpart to 0.8.16's portfolio write tier (server tooling), and a `switch_product` bug fix. From batch-3 dogfooding (portfolio strategy reasoning across the full multi-product workspace). All additive; existing files stay valid.
+
+### Added
+- `contributes_to` cross-product edge type in `UPG_CROSS_EDGE_TYPES` (union 7 → 8): the directional OKR rollup / alignment edge, subordinate → superior (product `objective` → company `objective`, product `key_result` → company `key_result`, product `outcome` → company `outcome`). Unlike the symmetric `shares_*` peer edges it is hierarchical, so a portfolio can answer "which company objective is this product serving?" and "which company KRs have no product driving them?". Additive; existing files stay valid. Decision: `2026-06-09-cross-product-okr-alignment-edge.md` (batch-3 #14).
+- (MCP server, not core spec) `portfolio_query` + `portfolio_digest`: read node content and health digests ACROSS products in one call — the multi-product `query` / `get_graph_digest` — without `switch_product`. The read counterpart to the 0.8.16 portfolio write tier. Read-only and parallel-safe: the active product is read from the live store, every other product via a transient read-only load. Tool surface 106 → 108 (batch-3 #13).
+- (SDK) `UPGFileStore.loadReadOnly()`: parse + normalise + index a `.upg` without starting a file watcher or taking a lock, for transient cross-product reads.
+
+### Fixed
+- (MCP server) `switch_product` bare-name resolution now anchors to the workspace `.upg/` directory first and requires a regular file, so a bare product name (e.g. `sanity`) that collides with a sibling source directory (`sanity/`) loads `.upg/sanity.upg` instead of throwing `EISDIR` (batch-3 #12).
+
+### Deferred
+- Cross-product **write** (writing nodes/edges into non-active products without `switch_product`) is tracked as batch-4 — the write counterpart to this read layer. Strategic linkage across products is already expressible today via `contributes_to` cross-edges (no switching required); only content propagation into product internals is outstanding.
+
+---
+
+## [0.9.0] - 2026-06-09
 
 **Breaking type rename (with migration) + framework-scoped scoring completion.** Two coordinated spec changes ship in this cut, both additive + deprecate (existing `.upg` files dual-read via `UPG_MIGRATIONS['0.9.0']`): the `theme` → `roadmap_theme` rename (UPG-660, completing the N6 four-way theme-family disambiguation) and the framework-scoped scoring migration for `solution` + `opportunity` (UPG-644, completing UPG-595). Decisions: `2026-06-09-theme-roadmap-theme-rename.md`, `2026-06-05-framework-scoped-scoring-completion.md`.
 
@@ -27,7 +64,7 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - `theme` (`ent_080`): retained in the type union and resolvable via the migration map for the 0.9.x dual-read window; `replacement: 'roadmap_theme'`. Loaders retarget old nodes and the four old edge keys automatically.
 - `solution`: `reach`, `impact`, `confidence`, `effort`, `rice_score` (apply `rice-scoring`). `timeline` is unaffected (intrinsic).
 - `opportunity`: `reach`, `frequency`, `pain`, `opportunity_score` (apply `opportunity-sizing`).
-- Native scoring fields are signalled deprecated via `@deprecated` JSDoc (flowing into the generated `UPG_PROPERTY_SCHEMA` descriptions) and stay dual-read for 0.9.x. Removal plus the `migrate_properties` lift onto `framework_exercise` includes-edges lands in 0.9.1, **after** consumers read from the edge (never before: a premature data move silently flattens sort/quadrant surfaces to zero).
+- Native scoring fields are signalled deprecated via `@deprecated` JSDoc (flowing into the generated `UPG_PROPERTY_SCHEMA` descriptions) and stay dual-read for 0.9.x. Removal plus the `migrate_properties` lift onto `framework_exercise` includes-edges lands in a later 0.9.x cut (originally earmarked 0.9.1; 0.9.1 became the batch-3 read layer), **after** consumers read from the edge (never before: a premature data move silently flattens sort/quadrant surfaces to zero).
 - Follow-up (0.9.x): a machine-readable `PropertyDefinition.deprecated` field so the property-registry generator emits it and the public GraphQL generator can mark removed scalars `@deprecated` rather than dropping them silently.
 
 ---

package/dist/index.cjs

@@ -1484,8 +1484,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" },
@@ -2951,7 +2967,8 @@ var UPG_CROSS_EDGE_TYPES = [
   "depends_on_product",
   "cannibalises",
   "succeeds",
-  "hosts"
+  "hosts",
+  "contributes_to"
 ];
 
 // src/registry/entity-type-resolution.ts
@@ -3242,8 +3259,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
@@ -7796,6 +7818,20 @@ function getSplitMigrations(fromVersion, toVersion) {
   return result;
 }
 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
@@ -10294,6 +10330,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." },
@@ -10325,7 +10362,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"' },
@@ -10336,8 +10373,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: {
@@ -18260,8 +18298,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"] },
@@ -20326,7 +20369,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",
@@ -23623,6 +23670,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" }
   }
 ];
 function getAntiPatternById(id) {
@@ -26145,7 +26226,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.9.0";
+var UPG_VERSION = "0.9.2";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();