@unified-product-graph/core 0.17.3 → 0.17.5

package/README.md

@@ -7,7 +7,7 @@
 
 The TypeScript core for the **Unified Product Graph (UPG)**, an open specification that gives product tools a shared vocabulary for entities, edges, and frameworks.
 
-318 entity types across 37 domains. 1017 typed edges. 46 canonical framework definitions, with more added as each is reviewed.
+319 entity types across 37 domains. 1024 typed edges. 46 canonical framework definitions, with more added as each is reviewed.
 
 ## Install
 

package/dist/index.cjs

@@ -39,6 +39,7 @@ __export(index_exports, {
   COVERAGE_ANTI_PATTERNS: () => COVERAGE_ANTI_PATTERNS,
   DEFAULT_ENTITY_EMOJI: () => DEFAULT_ENTITY_EMOJI,
   DEFERRED_PROPOSED_BY_CONTRACT: () => DEFERRED_PROPOSED_BY_CONTRACT,
+  DEFER_EDGE_PROPERTY_SCHEMA: () => DEFER_EDGE_PROPERTY_SCHEMA,
   DISCOVERY_RESEARCH_VALIDATION_PLAYBOOK: () => DISCOVERY_RESEARCH_VALIDATION_PLAYBOOK,
   ENGINEERING_PLATFORM_PLAYBOOK: () => ENGINEERING_PLATFORM_PLAYBOOK,
   ENTITY_EMOJI: () => ENTITY_EMOJI,
@@ -70,6 +71,7 @@ __export(index_exports, {
   UPG_CROSS_EDGE_TYPES: () => UPG_CROSS_EDGE_TYPES,
   UPG_CROSS_ELIGIBLE_CATALOG_EDGE_TYPES: () => UPG_CROSS_ELIGIBLE_CATALOG_EDGE_TYPES,
   UPG_CROSS_ONLY_EDGE_TYPES: () => UPG_CROSS_ONLY_EDGE_TYPES,
+  UPG_DELIBERATE_ONLY_EDGE_TYPES: () => UPG_DELIBERATE_ONLY_EDGE_TYPES,
   UPG_DEPRECATED_TYPES: () => UPG_DEPRECATED_TYPES,
   UPG_DOMAINS: () => UPG_DOMAINS,
   UPG_DOMAIN_ACTIVATION: () => UPG_DOMAIN_ACTIVATION,
@@ -201,6 +203,7 @@ __export(index_exports, {
   isCanonicalProductStage: () => isCanonicalProductStage,
   isContainmentFreeType: () => isContainmentFreeType,
   isCrossProductEligible: () => isCrossProductEligible,
+  isDeliberateOnlyEdge: () => isDeliberateOnlyEdge,
   isDeprecatedType: () => isDeprecatedType,
   isDomainGuideStep: () => isDomainGuideStep,
   isEntitySequenceStep: () => isEntitySequenceStep,
@@ -267,7 +270,8 @@ var UPG_DOMAINS = [
       "strategic_pillar",
       "assumption",
       "decision",
-      "constraint"
+      "constraint",
+      "strategic_question"
     ]
   },
   {
@@ -786,6 +790,10 @@ var UPG_ENTITY_META = [
   { name: "assumption", type_id: "ent_014", maturity: "stable", since: "0.1.0" },
   { name: "decision", type_id: "ent_015", maturity: "stable", since: "0.1.0" },
   { name: "constraint", type_id: "ent_348", maturity: "stable", since: "0.4.3" },
+  // (0.17.4) Strategy-domain sibling of research_question / design_question,
+  // completing the domain-question triad. An open coordination/ownership question
+  // a plan is exposed to (distinct from `assumption`, which the plan is built on).
+  { name: "strategic_question", type_id: "ent_357", maturity: "proposed", since: "0.17.4" },
   // ── User ──
   { name: "persona", type_id: "ent_016", maturity: "stable", since: "0.1.0" },
   { name: "job", type_id: "ent_017", maturity: "stable", since: "0.1.0" },
@@ -1260,6 +1268,12 @@ var CLASSIFICATION_EDGE_PROPERTY_SCHEMA = {
     description: "Optional. A source URL, or a competitor_signal / evidence node id backing the classification. Mirrors feature_rivals_competitor_feature.evidence (free text or a node id)."
   }
 };
+var DEFER_EDGE_PROPERTY_SCHEMA = {
+  deferred_to: {
+    type: "string",
+    description: 'Target period the parked work is deferred to. Freeform, mirroring strategic_theme.time_horizon. @example "Q4 2026", "FY27", "next release".'
+  }
+};
 var UPG_EDGE_CATALOG = {
   // ── Part 1: Core Narrative Spine (Ring 1) ──────────────────────────────────
   // 1.1 User Domain
@@ -2290,6 +2304,11 @@ var UPG_EDGE_CATALOG = {
   document_describes_positioning: { forward_verb: "describes", reverse_verb: "described_by", classification: "semantic", source_type: "document", target_type: "positioning" },
   document_describes_decision: { forward_verb: "describes", reverse_verb: "described_by", classification: "semantic", source_type: "document", target_type: "decision" },
   document_contains_insight: { forward_verb: "contains", reverse_verb: "contained_in", classification: "semantic", source_type: "document", target_type: "insight" },
+  // Research-provenance containment (0.17.5): a synthesis document is walkable
+  // to the evidence it sourced. Within-graph containment (the document and the
+  // evidence co-reside), so NOT cross_product_eligible.
+  document_contains_quote: { forward_verb: "contains", reverse_verb: "contained_in", classification: "semantic", source_type: "document", target_type: "quote" },
+  document_contains_observation: { forward_verb: "contains", reverse_verb: "contained_in", classification: "semantic", source_type: "document", target_type: "observation" },
   // 5.3 Customer Education & Training Domain
   product_educates_via_education_program: { forward_verb: "educates_via", reverse_verb: "educates", classification: "hierarchy", source_type: "product", target_type: "education_program" },
   education_program_teaches_via_tutorial: { forward_verb: "teaches_via", reverse_verb: "teaches", classification: "hierarchy", source_type: "education_program", target_type: "tutorial" },
@@ -3334,7 +3353,45 @@ var UPG_EDGE_CATALOG = {
   // Operating-lifecycle cross-edges (0.11.6): a product's journey phase realises a canonical
   // operating stage (the cross-surface join key); a stage is measured by a rollup metric (loop close).
   journey_phase_realises_operating_stage: { forward_verb: "realises", reverse_verb: "realised_by", classification: "cross-domain", source_type: "journey_phase", target_type: "operating_stage", cross_product_eligible: true },
-  operating_stage_measured_by_metric: { forward_verb: "measured_by", reverse_verb: "measures", classification: "cross-domain", source_type: "operating_stage", target_type: "metric" }
+  operating_stage_measured_by_metric: { forward_verb: "measured_by", reverse_verb: "measures", classification: "cross-domain", source_type: "operating_stage", target_type: "metric" },
+  // ── OKR planning coverage (0.17.4) ──────────────────────────────────────────
+  // Reconciling the strategy graph against a live planning doc surfaced texture
+  // the objective — the node every OKR doc organises itself around — could not
+  // reach: cross-team dependencies and deferred (out-of-scope) work.
+  // objective ↔ dependency. Every OKR in the source doc carries a dependency
+  // table ("which other team's work this depends on"). `dependency` (team_org)
+  // already carries dependency_type / criticality / target_date; it was
+  // reachable only from `team`. An objective DEPENDS ON a dependency; the
+  // dependency BLOCKS the objective (explicit mirror, not left implicit).
+  // Cross-domain, not hierarchy: a dependency is parented under its owning team,
+  // so an objective references it laterally rather than containing it. Both are
+  // cross_product_eligible — a Studio objective can depend on a dependency owned
+  // by another team's graph within the portfolio (0.17.3 locked predicate).
+  objective_depends_on_dependency: { forward_verb: "depends_on", reverse_verb: "dependency_of", classification: "cross-domain", source_type: "objective", target_type: "dependency", cross_product_eligible: true },
+  dependency_blocks_objective: { forward_verb: "blocks", reverse_verb: "blocked_by", classification: "cross-domain", source_type: "dependency", target_type: "objective", cross_product_eligible: true },
+  // objective / initiative → strategic_question. A planning doc's "Risks & Open
+  // Questions" section names unresolved coordination questions the plan is
+  // exposed to (who owns a capability across teams after a reorg). The
+  // strategy-domain sibling of research_question / design_question. The question
+  // is raised under (contained by) the objective or initiative that surfaces it,
+  // so hierarchy — mirroring initiative_assumes_assumption. Within-graph: the
+  // question node is authored alongside its objective, so NOT
+  // cross_product_eligible (the cross-team nature lives in the question text, not
+  // in a cross-graph edge).
+  objective_raises_strategic_question: { forward_verb: "raises", reverse_verb: "raised_by", classification: "hierarchy", source_type: "objective", target_type: "strategic_question" },
+  initiative_raises_strategic_question: { forward_verb: "raises", reverse_verb: "raised_by", classification: "hierarchy", source_type: "initiative", target_type: "strategic_question" },
+  // objective → feature / capability (the defer / out-of-scope edge). Every OKR
+  // in the source doc carries an explicit "Out of scope" list, load-bearing for
+  // keeping a quarter from silently expanding (localization deferred to Q4,
+  // another team's feature work parked). Modelled as an edge to the real feature
+  // or capability parked for later, not a scalar exclusion string, so the parked
+  // work stays queryable and connected. The `deferred_to` edge property carries
+  // the temporal target. feature is product_spec (cross-domain); capability is
+  // intra-strategy (semantic). Both cross_product_eligible: deferring another
+  // product's feature or capability, authored in a different graph within the
+  // portfolio, fits the 0.17.3 locked predicate.
+  objective_defers_feature: { forward_verb: "defers", reverse_verb: "deferred_by", classification: "cross-domain", source_type: "objective", target_type: "feature", carries_properties: true, property_schema: DEFER_EDGE_PROPERTY_SCHEMA, cross_product_eligible: true, deliberate_only: true },
+  objective_defers_capability: { forward_verb: "defers", reverse_verb: "deferred_by", classification: "semantic", source_type: "objective", target_type: "capability", carries_properties: true, property_schema: DEFER_EDGE_PROPERTY_SCHEMA, cross_product_eligible: true, deliberate_only: true }
 };
 var UPG_CROSS_ELIGIBLE_CATALOG_EDGE_TYPES = Object.keys(UPG_EDGE_CATALOG).filter(
   (k) => UPG_EDGE_CATALOG[k].cross_product_eligible === true
@@ -3343,6 +3400,13 @@ function isCrossProductEligible(type) {
   const def = UPG_EDGE_CATALOG[type];
   return def?.cross_product_eligible === true;
 }
+var UPG_DELIBERATE_ONLY_EDGE_TYPES = Object.keys(UPG_EDGE_CATALOG).filter(
+  (k) => UPG_EDGE_CATALOG[k].deliberate_only === true
+);
+function isDeliberateOnlyEdge(type) {
+  const def = UPG_EDGE_CATALOG[type];
+  return def?.deliberate_only === true;
+}
 var UPG_POLYMORPHIC_EDGE_KEYS = [
   // Universal semantic verbs
   "node_informs_node",
@@ -3710,7 +3774,9 @@ var UPG_VALID_CHILDREN = {
   // where self-nesting genuinely lives, not on `experiment`).
   experiment_run: ["learning", "evidence", "metric", "experiment_run"],
   // ── OKR hierarchy ──────────────────────────────────────────────────────────
-  objective: ["key_result", "metric"],
+  // strategic_question (0.17.4): an open coordination question raised under an
+  // objective (objective_raises_strategic_question, hierarchy).
+  objective: ["key_result", "metric", "strategic_question"],
   key_result: ["metric"],
   // ── Strategic cascade: vision → mission → strategic_pillar → strategic_theme →
   //    { initiative, objective } ───────────────────────────────────────────────
@@ -3735,7 +3801,7 @@ var UPG_VALID_CHILDREN = {
   // catalog (hierarchy, strategic_theme → objective, reverse_verb: rolls_up_to;
   // renamed from objective_rolls_up_to_strategic_theme in UPG-676).
   strategic_theme: ["initiative", "objective"],
-  initiative: ["assumption"],
+  initiative: ["assumption", "strategic_question"],
   // v0.5.2 (UPG-528): capability decomposes into sub-capabilities (Wardley
   // value-chain spine) and is realised by user-facing features. Pairs with
   // `capability_depends_on_capability` and `capability_implemented_by_feature`
@@ -4808,6 +4874,15 @@ var ASSUMPTION_LIFECYCLE = {
     }
   ]
 };
+var STRATEGIC_QUESTION_LIFECYCLE = {
+  entity_type: "strategic_question",
+  initial_phase: "open",
+  terminal_phases: ["resolved"],
+  phases: [
+    { id: "open", label: "Open", description: "The question has been raised but not yet answered. The plan is exposed to it.", transitions_to: ["resolved"] },
+    { id: "resolved", label: "Resolved", description: "The question has been answered; the resolution is captured. The plan is no longer exposed to it. May reopen if the answer unravels.", transitions_to: ["open"] }
+  ]
+};
 var OUTCOME_LIFECYCLE = {
   entity_type: "outcome",
   initial_phase: "identified",
@@ -6485,6 +6560,7 @@ var UPG_LIFECYCLES = [
   INITIATIVE_LIFECYCLE,
   STRATEGIC_PILLAR_LIFECYCLE,
   ASSUMPTION_LIFECYCLE,
+  STRATEGIC_QUESTION_LIFECYCLE,
   FEATURE_AREA_LIFECYCLE,
   FEATURE_LIFECYCLE,
   EPIC_LIFECYCLE,
@@ -12279,7 +12355,8 @@ var UPG_PROPERTY_SCHEMA = {
     session_ref: { type: "string", description: "Capturing session reference. Convenience field; the canonical relationship to study/session is an edge per P14. Retained as a lightweight context anchor for AI inference." },
     is_highlighted: { type: "boolean", description: "Flagged as a highlight. Absorbed from the deprecated Highlight entity." },
     highlight_tag: { type: "string", description: 'Free-form highlight type tag. @example "pain", "delight", "behaviour", "moment of clarity"' },
-    sentiment: { type: "string", enum: ["positive", "neutral", "negative", "mixed"], description: "Structured sentiment. Tools like Dovetail and EnjoyHQ converge on these four values. More precise than `highlight_tag` for aggregation." }
+    sentiment: { type: "string", enum: ["positive", "neutral", "negative", "mixed"], description: "Structured sentiment. Tools like Dovetail and EnjoyHQ converge on these four values. More precise than `highlight_tag` for aggregation." },
+    source_url: { type: "string", description: "Stable deep-link to the exact moment this observation was captured in the originating recording or transcript. A per-moment locator, not a study-level link. Distinct from `session_ref`, which holds an opaque session ID.", modifier: "volatile" }
   },
   // OnCallRotationProperties: On-call rotation.
   on_call_rotation: {
@@ -12323,7 +12400,8 @@ var UPG_PROPERTY_SCHEMA = {
   participant: {
     alias: { type: "string", description: 'Anonymous alias for privacy (e.g. "P01")' },
     recruit_source: { type: "string", description: "How the participant was recruited" },
-    consent_status: { type: "string", enum: ["pending", "given", "withdrawn"], description: "Current consent status for data usage" }
+    consent_status: { type: "string", enum: ["pending", "given", "withdrawn"], description: "Current consent status for data usage" },
+    source_url: { type: "string", description: "Stable deep-link to the exact moment this participant appears in the originating recording or transcript. A per-moment locator, not a study-level link.", modifier: "volatile" }
   },
   // PartnerProgramProperties: Partner program.
   partner_program: {
@@ -12546,7 +12624,8 @@ var UPG_PROPERTY_SCHEMA = {
   // QuoteProperties: Verbatim quote from a participant.
   quote: {
     text: { type: "string", description: "Quoted text" },
-    timestamp: { type: "string", description: "When said (ISO timestamp or session offset)" }
+    timestamp: { type: "string", description: "When said (ISO timestamp or session offset)" },
+    source_url: { type: "string", description: "Stable deep-link to the exact moment this quote was spoken in the originating recording or transcript. A per-moment locator, not a study-level link.", modifier: "volatile" }
   },
   // QuoteDocumentProperties: Quote document.
   quote_document: {
@@ -12961,6 +13040,15 @@ var UPG_PROPERTY_SCHEMA = {
     time_horizon: { type: "string", description: 'Standing / multi-year horizon, often open-ended (a pillar is durable). @example "3 years", "2026-2028", "ongoing"' },
     success_indicator: { type: "string", description: "How the business knows this durable pillar is on track. Narrative, not a metric edge. A strategic_theme deliberately has no success_indicator: it is measured through its child objectives, not on its own." }
   },
+  // StrategicQuestionProperties: StrategicQuestion entity. An open coordination or
+  // ownership question a plan is exposed to (strategy sibling of research_question /
+  // design_question). `status` is the node lifecycle (open -> resolved).
+  strategic_question: {
+    question: { type: "string", description: "The question itself. Primary content." },
+    context: { type: "string", description: "Context that surfaced the question: the reorg, the boundary, the unowned area." },
+    resolution: { type: "string", description: "The answer, captured when the question moves to `resolved`." },
+    priority: { type: "string", enum: ["urgent", "high", "medium", "low", "none"], description: "Importance to resolve relative to other open questions." }
+  },
   // StrategicThemeProperties: StrategicTheme entity. A time-bound thrust WITHIN a
   // strategic_pillar (distinct cascade level, UPG-692 T3.3) — measured through its
   // child objectives, so it carries no success_indicator of its own.
@@ -19989,6 +20077,7 @@ var ENTITY_EMOJI = {
   stakeholder: "\u{1F9D1}\u200D\u{1F4BC}",
   status_report: "\u{1F4C4}",
   strategic_pillar: "\u{1F3DB}\uFE0F",
+  strategic_question: "\u2754",
   strategic_theme: "\u{1F9F5}",
   subscription: "\u{1F502}",
   success_milestone: "\u{1F389}",
@@ -20546,6 +20635,7 @@ var STANDARD_LABELS = {
   value_stream: { alt_labels: ["value chain", "stream"] },
   strategic_pillar: { alt_labels: ["pillar", "foundation"] },
   assumption: { alt_labels: ["belief", "working assumption", "premise"] },
+  strategic_question: { alt_labels: ["open question", "coordination question", "ownership question"] },
   // User layer
   job_step: { alt_labels: ["job stage", "job phase", "job map step"] },
   switching_cost: { alt_labels: ["lock-in", "migration cost", "switching barrier"] },
@@ -22975,7 +23065,13 @@ var USER_RESEARCH_GUIDE = {
   anti_patterns: [
     { description: "Insights without evidence: every insight must trace back to observations and quotes" },
     { description: "Orphan quotes: quotes should belong to observations, not float independently" },
-    { description: "Research studies without questions: always define what you want to learn before starting" }
+    { description: "Research studies without questions: always define what you want to learn before starting" },
+    {
+      name: "Study conflation",
+      affected_entity: "research_study",
+      description: "Do not merge multiple research rounds with different stated goals into one `research_study` (or one participant pool) just because they were synthesized into the same downstream document. If two rounds have different research questions, they are different `research_study` nodes, even if an analyst wrote them up together.",
+      remediation: "Verify against the *original* recording or session metadata, not the synthesis doc's grouping."
+    }
   ]
 };
 var MARKET_INTELLIGENCE_GUIDE = {
@@ -23090,7 +23186,7 @@ var STRATEGY_GUIDE = {
   // entries are later additions appended in chronological-introduction
   // order. Placement reflects the order in which they would naturally be
   // authored after the canonical strategy spine.
-  creation_sequence: ["product", "vision", "mission", "outcome", "objective", "key_result", "metric", "metric_quality_assessment", "strategic_theme", "strategic_pillar", "initiative", "capability", "value_stream", "assumption", "decision", "constraint"],
+  creation_sequence: ["product", "vision", "mission", "outcome", "objective", "key_result", "metric", "metric_quality_assessment", "strategic_theme", "strategic_pillar", "initiative", "capability", "value_stream", "assumption", "strategic_question", "decision", "constraint"],
   patterns: [
     {
       name: "Strategic Cascade",
@@ -23108,13 +23204,16 @@ var STRATEGY_GUIDE = {
   required_bridges: [
     { edge_type: "outcome_reveals_opportunity", target_domain: "discovery", when: "Outcomes should connect to the opportunities that deliver them" },
     { edge_type: "outcome_delivered_by_feature", target_domain: "product_spec", when: "Strategic outcomes should decompose into shipped features" },
-    { edge_type: "assumption_becomes_hypothesis", target_domain: "validation", when: "Risky assumptions should become testable hypotheses" }
+    { edge_type: "assumption_becomes_hypothesis", target_domain: "validation", when: "Risky assumptions should become testable hypotheses" },
+    { edge_type: "objective_depends_on_dependency", target_domain: "team_org", when: "An objective that hinges on cross-team work should name the dependency it is exposed to" },
+    { edge_type: "objective_defers_feature", target_domain: "product_spec", when: "Work an objective explicitly puts out of scope for now should point at the deferred feature with a deferred_to period, not silently vanish from the quarter" }
   ],
   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: "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)." }
+    { 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)." },
+    { description: "Overloading assumption for open questions: an assumption is a premise the plan is built on and resolves by being tested (assumption_becomes_hypothesis). An unresolved coordination or ownership question the plan is exposed to (who owns a capability across teams, where a boundary falls after a reorg) is a strategic_question, raised under the objective or initiative it hangs off. Do not force one into the other." }
   ]
 };
 var PRODUCT_SPEC_GUIDE = {
@@ -27167,6 +27266,10 @@ var UPG_REGIONS = [
         type: "assumption",
         role: "leaf"
       },
+      {
+        type: "strategic_question",
+        role: "leaf"
+      },
       {
         type: "constraint",
         role: "leaf"
@@ -27192,6 +27295,8 @@ var UPG_REGIONS = [
       "strategic_pillar_decided_via_decision",
       "strategic_theme_pursues_initiative",
       "initiative_assumes_assumption",
+      "objective_raises_strategic_question",
+      "initiative_raises_strategic_question",
       "initiative_drives_outcome",
       "objective_achieved_through_key_result",
       "objective_measured_by_metric",
@@ -29876,7 +29981,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.17.3";
+var UPG_VERSION = "0.17.5";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -29950,6 +30055,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   COVERAGE_ANTI_PATTERNS,
   DEFAULT_ENTITY_EMOJI,
   DEFERRED_PROPOSED_BY_CONTRACT,
+  DEFER_EDGE_PROPERTY_SCHEMA,
   DISCOVERY_RESEARCH_VALIDATION_PLAYBOOK,
   ENGINEERING_PLATFORM_PLAYBOOK,
   ENTITY_EMOJI,
@@ -29981,6 +30087,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   UPG_CROSS_EDGE_TYPES,
   UPG_CROSS_ELIGIBLE_CATALOG_EDGE_TYPES,
   UPG_CROSS_ONLY_EDGE_TYPES,
+  UPG_DELIBERATE_ONLY_EDGE_TYPES,
   UPG_DEPRECATED_TYPES,
   UPG_DOMAINS,
   UPG_DOMAIN_ACTIVATION,
@@ -30112,6 +30219,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   isCanonicalProductStage,
   isContainmentFreeType,
   isCrossProductEligible,
+  isDeliberateOnlyEdge,
   isDeprecatedType,
   isDomainGuideStep,
   isEntitySequenceStep,