@unified-product-graph/core 0.8.5 → 0.8.7

package/dist/index.js

@@ -8475,209 +8475,6 @@ function rotateSlug(node, next) {
   return node;
 }
 
-// src/grammar/validate.ts
-var crossProductEdgeTypeSet = new Set(UPG_CROSS_EDGE_TYPES);
-function validateUPGDocument(doc) {
-  const errors = [];
-  const warnings = [];
-  if (!doc || typeof doc !== "object") {
-    return { valid: false, errors: [{ path: "$", message: "Document must be an object" }], warnings };
-  }
-  const d = doc;
-  if (!d.upg_version || typeof d.upg_version !== "string") {
-    errors.push({ path: "$.upg_version", message: "upg_version is required and must be a string" });
-  }
-  if (!d.exported_at || typeof d.exported_at !== "string") {
-    errors.push({ path: "$.exported_at", message: "exported_at is required and must be an ISO 8601 string" });
-  }
-  if (!d.source || typeof d.source !== "object") {
-    errors.push({ path: "$.source", message: "source is required and must be an object" });
-  } else {
-    const source = d.source;
-    if (!source.tool || typeof source.tool !== "string") {
-      errors.push({ path: "$.source.tool", message: "source.tool is required and must be a string" });
-    }
-  }
-  if (!d.product || typeof d.product !== "object") {
-    errors.push({ path: "$.product", message: "product is required and must be an object" });
-  } else {
-    const product = d.product;
-    if (!product.id || typeof product.id !== "string") {
-      errors.push({ path: "$.product.id", message: "product.id is required and must be a string" });
-    }
-    if (!product.title || typeof product.title !== "string") {
-      errors.push({ path: "$.product.title", message: "product.title is required and must be a string" });
-    }
-  }
-  const allKnownTypes = new Set(getTypes());
-  const allKnownEdgeTypes = new Set(Object.keys(UPG_EDGE_CATALOG));
-  if (!Array.isArray(d.nodes)) {
-    errors.push({ path: "$.nodes", message: "nodes is required and must be an array" });
-  } else {
-    const nodeIds = /* @__PURE__ */ new Set();
-    const nodesById = /* @__PURE__ */ new Map();
-    d.nodes.forEach((node, i) => {
-      const path = `$.nodes[${i}]`;
-      if (!node || typeof node !== "object") {
-        errors.push({ path, message: "Each node must be an object" });
-        return;
-      }
-      const n = node;
-      if (!n.id || typeof n.id !== "string") {
-        errors.push({ path: `${path}.id`, message: "Node id is required and must be a string" });
-      } else {
-        if (nodeIds.has(n.id)) {
-          errors.push({ path: `${path}.id`, message: `Duplicate node id: ${n.id}` });
-        }
-        nodeIds.add(n.id);
-        nodesById.set(n.id, n);
-      }
-      if (!n.type || typeof n.type !== "string") {
-        errors.push({ path: `${path}.type`, message: "Node type is required and must be a string" });
-      } else if (!allKnownTypes.has(n.type)) {
-        warnings.push({ path: `${path}.type`, message: `Unknown UPG type: "${n.type}". Node will be preserved with its original type.` });
-      }
-      if (!n.title || typeof n.title !== "string") {
-        errors.push({ path: `${path}.title`, message: "Node title is required and must be a string" });
-      }
-    });
-    if (!Array.isArray(d.edges)) {
-      errors.push({ path: "$.edges", message: "edges is required and must be an array" });
-    } else {
-      d.edges.forEach((edge, i) => {
-        const path = `$.edges[${i}]`;
-        if (!edge || typeof edge !== "object") {
-          errors.push({ path, message: "Each edge must be an object" });
-          return;
-        }
-        const e = edge;
-        if (!e.id || typeof e.id !== "string") {
-          errors.push({ path: `${path}.id`, message: "Edge id is required and must be a string" });
-        }
-        if (typeof e.type === "string" && crossProductEdgeTypeSet.has(e.type)) {
-          errors.push({
-            path: `${path}.type`,
-            message: `Cross-product edge type "${e.type}" must live in portfolio.cross_edges[], not product edges[].`
-          });
-          return;
-        }
-        if (!e.source || typeof e.source !== "string") {
-          errors.push({ path: `${path}.source`, message: "Edge source is required and must be a string" });
-        } else if (!nodeIds.has(e.source)) {
-          errors.push({ path: `${path}.source`, message: `Edge source references unknown node id: ${e.source}` });
-        }
-        if (!e.target || typeof e.target !== "string") {
-          errors.push({ path: `${path}.target`, message: "Edge target is required and must be a string" });
-        } else if (!nodeIds.has(e.target)) {
-          errors.push({ path: `${path}.target`, message: `Edge target references unknown node id: ${e.target}` });
-        }
-        if (!e.type || typeof e.type !== "string") {
-          errors.push({ path: `${path}.type`, message: "Edge type is required and must be a string" });
-        } else if (!allKnownEdgeTypes.has(e.type)) {
-          warnings.push({
-            path: `${path}.type`,
-            message: `Unknown edge type: "${e.type}". Edge preserved but not in the edge registry.`
-          });
-        }
-      });
-      const valueToAxis = /* @__PURE__ */ new Map();
-      const edgesArr = d.edges;
-      for (const edge of edgesArr) {
-        if (!edge || typeof edge !== "object") continue;
-        const e = edge;
-        if (e.type === "classification_axis_includes_classification_value" && typeof e.source === "string" && typeof e.target === "string") {
-          valueToAxis.set(e.target, e.source);
-        }
-      }
-      for (const [id, n] of nodesById.entries()) {
-        if (n.type !== "classification_value") continue;
-        if (valueToAxis.has(id)) continue;
-        const pid = n.parent_id;
-        if (typeof pid === "string") {
-          const parent = nodesById.get(pid);
-          if (parent && parent.type === "classification_axis") {
-            valueToAxis.set(id, pid);
-          }
-        }
-      }
-      const axesPerAnalysis = /* @__PURE__ */ new Map();
-      for (const edge of edgesArr) {
-        if (!edge || typeof edge !== "object") continue;
-        const e = edge;
-        if (e.type === "competitive_analysis_dimensioned_by_classification_axis" && typeof e.source === "string") {
-          axesPerAnalysis.set(e.source, (axesPerAnalysis.get(e.source) ?? 0) + 1);
-        }
-      }
-      d.nodes.forEach((node, i) => {
-        if (!node || typeof node !== "object") return;
-        const n = node;
-        if (n.type !== "competitive_analysis") return;
-        const props = n.properties;
-        if (!props || typeof props !== "object") return;
-        const empty = props.empty_cells;
-        if (!Array.isArray(empty)) return;
-        const axisCount = axesPerAnalysis.get(n.id ?? "") ?? 0;
-        if (axisCount !== 2) {
-          warnings.push({
-            path: `$.nodes[${i}].properties.empty_cells`,
-            message: `empty_cells is meaningful only on a 2-axis competitive_analysis; this node is dimensioned by ${axisCount} classification_axis ${axisCount === 1 ? "child" : "children"}.`
-          });
-        }
-        empty.forEach((cell, j) => {
-          const cpath = `$.nodes[${i}].properties.empty_cells[${j}]`;
-          if (!cell || typeof cell !== "object") {
-            errors.push({ path: cpath, message: "empty_cells entry must be an object" });
-            return;
-          }
-          const c = cell;
-          const aRef = c.axis_a_value_ref;
-          const bRef = c.axis_b_value_ref;
-          if (typeof aRef !== "string") {
-            errors.push({ path: `${cpath}.axis_a_value_ref`, message: "axis_a_value_ref is required and must be a string" });
-          }
-          if (typeof bRef !== "string") {
-            errors.push({ path: `${cpath}.axis_b_value_ref`, message: "axis_b_value_ref is required and must be a string" });
-          }
-          if (typeof aRef !== "string" || typeof bRef !== "string") return;
-          const aNode = nodesById.get(aRef);
-          const bNode = nodesById.get(bRef);
-          if (!aNode) {
-            errors.push({ path: `${cpath}.axis_a_value_ref`, message: `Unknown node id: ${aRef}` });
-          } else if (aNode.type !== "classification_value") {
-            errors.push({ path: `${cpath}.axis_a_value_ref`, message: `Expected classification_value, found "${String(aNode.type)}" at ${aRef}` });
-          }
-          if (!bNode) {
-            errors.push({ path: `${cpath}.axis_b_value_ref`, message: `Unknown node id: ${bRef}` });
-          } else if (bNode.type !== "classification_value") {
-            errors.push({ path: `${cpath}.axis_b_value_ref`, message: `Expected classification_value, found "${String(bNode.type)}" at ${bRef}` });
-          }
-          if (aNode && bNode && aNode.type === "classification_value" && bNode.type === "classification_value") {
-            const aAxis = valueToAxis.get(aRef);
-            const bAxis = valueToAxis.get(bRef);
-            if (aAxis && bAxis && aAxis === bAxis) {
-              errors.push({
-                path: cpath,
-                message: `empty_cells references two classification_values from the same axis (${aAxis}); axis_a and axis_b must come from distinct classification_axis parents.`
-              });
-            }
-          }
-          const kind = c.rationale_kind;
-          if (kind !== void 0 && kind !== "structural" && kind !== "ideological" && kind !== "opportunity") {
-            errors.push({
-              path: `${cpath}.rationale_kind`,
-              message: `rationale_kind must be one of 'structural' | 'ideological' | 'opportunity'; got "${String(kind)}".`
-            });
-          }
-        });
-      });
-    }
-  }
-  return { valid: errors.length === 0, errors, warnings };
-}
-function isUPGDocument(doc) {
-  return validateUPGDocument(doc).valid;
-}
-
 // src/properties/property-schema.ts
 var UPG_PROPERTY_SCHEMA = {
   // A11yAnnotationProperties: Accessibility annotation.
@@ -11836,59 +11633,346 @@ function getPropertySchema(entityType) {
   return UPG_PROPERTY_SCHEMA[entityType];
 }
 
-// src/frameworks/canonical.ts
-var UPG_FRAMEWORKS = [
-  {
-    "id": "opportunity-solution-tree",
-    "approach_ids": [
-      "trace"
-    ],
-    "name": "Opportunity Solution Tree",
-    "version": "1.0.0",
-    "description": "Map desired outcomes to opportunities, then branch into solutions and experiments. Ensures every solution traces back to a real user need.",
-    "category": "discovery",
-    "origin": {
-      "type": "practitioner",
-      "attribution": "Teresa Torres",
-      "description": "Introduced in Continuous Discovery Habits. Maps outcomes to opportunities, solutions, and experiments.",
-      "url": "https://www.producttalk.org/opportunity-solution-tree/",
-      "year": 2021,
-      "license": "published_methodology"
-    },
-    "tags": [
-      "discovery",
-      "tree"
-    ],
-    "slots": [
-      {
-        "label": "Root Outcome",
-        "entityTypeId": "outcome",
-        "description": "The desired business or user outcome"
-      },
-      {
-        "label": "Opportunities",
-        "entityTypeId": "opportunity",
-        "description": "User needs, pain points, or desires"
-      },
-      {
-        "label": "Solutions",
-        "entityTypeId": "solution",
-        "description": "Ideas to address each opportunity"
-      },
-      {
-        "label": "Experiments",
-        "entityTypeId": "experiment_run",
-        "description": "Tests to validate each solution"
-      }
-    ],
-    "data": {
-      "entity_types": [
-        {
-          "type": "outcome",
-          "role": "root"
-        },
-        {
-          "type": "opportunity",
+// src/grammar/validate.ts
+var crossProductEdgeTypeSet = new Set(UPG_CROSS_EDGE_TYPES);
+var CONTENT_DEPTH_WARNING_RULES = /* @__PURE__ */ new Set([
+  "property-type",
+  "property-enum",
+  "self-loop"
+]);
+function validateUPGDocument(doc) {
+  const errors = [];
+  const warnings = [];
+  if (!doc || typeof doc !== "object") {
+    return { valid: false, errors: [{ path: "$", message: "Document must be an object" }], warnings };
+  }
+  const d = doc;
+  if (!d.upg_version || typeof d.upg_version !== "string") {
+    errors.push({ path: "$.upg_version", message: "upg_version is required and must be a string" });
+  }
+  if (!d.exported_at || typeof d.exported_at !== "string") {
+    errors.push({ path: "$.exported_at", message: "exported_at is required and must be an ISO 8601 string" });
+  }
+  if (!d.source || typeof d.source !== "object") {
+    errors.push({ path: "$.source", message: "source is required and must be an object" });
+  } else {
+    const source = d.source;
+    if (!source.tool || typeof source.tool !== "string") {
+      errors.push({ path: "$.source.tool", message: "source.tool is required and must be a string" });
+    }
+  }
+  if (!d.product || typeof d.product !== "object") {
+    errors.push({ path: "$.product", message: "product is required and must be an object" });
+  } else {
+    const product = d.product;
+    if (!product.id || typeof product.id !== "string") {
+      errors.push({ path: "$.product.id", message: "product.id is required and must be a string" });
+    }
+    if (!product.title || typeof product.title !== "string") {
+      errors.push({ path: "$.product.title", message: "product.title is required and must be a string" });
+    }
+  }
+  const allKnownTypes = new Set(getTypes());
+  const allKnownEdgeTypes = new Set(Object.keys(UPG_EDGE_CATALOG));
+  if (!Array.isArray(d.nodes)) {
+    errors.push({ path: "$.nodes", message: "nodes is required and must be an array" });
+  } else {
+    const nodeIds = /* @__PURE__ */ new Set();
+    const nodesById = /* @__PURE__ */ new Map();
+    d.nodes.forEach((node, i) => {
+      const path = `$.nodes[${i}]`;
+      if (!node || typeof node !== "object") {
+        errors.push({ path, message: "Each node must be an object" });
+        return;
+      }
+      const n = node;
+      if (!n.id || typeof n.id !== "string") {
+        errors.push({ path: `${path}.id`, message: "Node id is required and must be a string" });
+      } else {
+        if (nodeIds.has(n.id)) {
+          errors.push({ path: `${path}.id`, message: `Duplicate node id: ${n.id}` });
+        }
+        nodeIds.add(n.id);
+        nodesById.set(n.id, n);
+      }
+      if (!n.type || typeof n.type !== "string") {
+        errors.push({ path: `${path}.type`, message: "Node type is required and must be a string" });
+      } else if (!allKnownTypes.has(n.type)) {
+        warnings.push({ path: `${path}.type`, message: `Unknown UPG type: "${n.type}". Node will be preserved with its original type.` });
+      }
+      if (!n.title || typeof n.title !== "string") {
+        errors.push({ path: `${path}.title`, message: "Node title is required and must be a string" });
+      } else if (n.title.trim().length === 0) {
+        errors.push({ path: `${path}.title`, message: "Node title must not be blank (whitespace-only)" });
+      }
+      if (typeof n.type === "string") {
+        validateNodeProperties(n, `${path}`, warnings);
+      }
+    });
+    if (!Array.isArray(d.edges)) {
+      errors.push({ path: "$.edges", message: "edges is required and must be an array" });
+    } else {
+      d.edges.forEach((edge, i) => {
+        const path = `$.edges[${i}]`;
+        if (!edge || typeof edge !== "object") {
+          errors.push({ path, message: "Each edge must be an object" });
+          return;
+        }
+        const e = edge;
+        if (!e.id || typeof e.id !== "string") {
+          errors.push({ path: `${path}.id`, message: "Edge id is required and must be a string" });
+        }
+        if (typeof e.type === "string" && crossProductEdgeTypeSet.has(e.type)) {
+          errors.push({
+            path: `${path}.type`,
+            message: `Cross-product edge type "${e.type}" must live in portfolio.cross_edges[], not product edges[].`
+          });
+          return;
+        }
+        if (!e.source || typeof e.source !== "string") {
+          errors.push({ path: `${path}.source`, message: "Edge source is required and must be a string" });
+        } else if (!nodeIds.has(e.source)) {
+          errors.push({ path: `${path}.source`, message: `Edge source references unknown node id: ${e.source}` });
+        }
+        if (!e.target || typeof e.target !== "string") {
+          errors.push({ path: `${path}.target`, message: "Edge target is required and must be a string" });
+        } else if (!nodeIds.has(e.target)) {
+          errors.push({ path: `${path}.target`, message: `Edge target references unknown node id: ${e.target}` });
+        }
+        if (typeof e.source === "string" && typeof e.target === "string" && e.source === e.target) {
+          warnings.push({
+            path: `${path}`,
+            message: `Self-loop edge: source and target are the same node ("${e.source}"). A node related to itself is almost always an error.`,
+            rule: "self-loop"
+          });
+        }
+        if (!e.type || typeof e.type !== "string") {
+          errors.push({ path: `${path}.type`, message: "Edge type is required and must be a string" });
+        } else if (!allKnownEdgeTypes.has(e.type)) {
+          warnings.push({
+            path: `${path}.type`,
+            message: `Unknown edge type: "${e.type}". Edge preserved but not in the edge registry.`
+          });
+        }
+      });
+      const valueToAxis = /* @__PURE__ */ new Map();
+      const edgesArr = d.edges;
+      for (const edge of edgesArr) {
+        if (!edge || typeof edge !== "object") continue;
+        const e = edge;
+        if (e.type === "classification_axis_includes_classification_value" && typeof e.source === "string" && typeof e.target === "string") {
+          valueToAxis.set(e.target, e.source);
+        }
+      }
+      for (const [id, n] of nodesById.entries()) {
+        if (n.type !== "classification_value") continue;
+        if (valueToAxis.has(id)) continue;
+        const pid = n.parent_id;
+        if (typeof pid === "string") {
+          const parent = nodesById.get(pid);
+          if (parent && parent.type === "classification_axis") {
+            valueToAxis.set(id, pid);
+          }
+        }
+      }
+      const axesPerAnalysis = /* @__PURE__ */ new Map();
+      for (const edge of edgesArr) {
+        if (!edge || typeof edge !== "object") continue;
+        const e = edge;
+        if (e.type === "competitive_analysis_dimensioned_by_classification_axis" && typeof e.source === "string") {
+          axesPerAnalysis.set(e.source, (axesPerAnalysis.get(e.source) ?? 0) + 1);
+        }
+      }
+      d.nodes.forEach((node, i) => {
+        if (!node || typeof node !== "object") return;
+        const n = node;
+        if (n.type !== "competitive_analysis") return;
+        const props = n.properties;
+        if (!props || typeof props !== "object") return;
+        const empty = props.empty_cells;
+        if (!Array.isArray(empty)) return;
+        const axisCount = axesPerAnalysis.get(n.id ?? "") ?? 0;
+        if (axisCount !== 2) {
+          warnings.push({
+            path: `$.nodes[${i}].properties.empty_cells`,
+            message: `empty_cells is meaningful only on a 2-axis competitive_analysis; this node is dimensioned by ${axisCount} classification_axis ${axisCount === 1 ? "child" : "children"}.`
+          });
+        }
+        empty.forEach((cell, j) => {
+          const cpath = `$.nodes[${i}].properties.empty_cells[${j}]`;
+          if (!cell || typeof cell !== "object") {
+            errors.push({ path: cpath, message: "empty_cells entry must be an object" });
+            return;
+          }
+          const c = cell;
+          const aRef = c.axis_a_value_ref;
+          const bRef = c.axis_b_value_ref;
+          if (typeof aRef !== "string") {
+            errors.push({ path: `${cpath}.axis_a_value_ref`, message: "axis_a_value_ref is required and must be a string" });
+          }
+          if (typeof bRef !== "string") {
+            errors.push({ path: `${cpath}.axis_b_value_ref`, message: "axis_b_value_ref is required and must be a string" });
+          }
+          if (typeof aRef !== "string" || typeof bRef !== "string") return;
+          const aNode = nodesById.get(aRef);
+          const bNode = nodesById.get(bRef);
+          if (!aNode) {
+            errors.push({ path: `${cpath}.axis_a_value_ref`, message: `Unknown node id: ${aRef}` });
+          } else if (aNode.type !== "classification_value") {
+            errors.push({ path: `${cpath}.axis_a_value_ref`, message: `Expected classification_value, found "${String(aNode.type)}" at ${aRef}` });
+          }
+          if (!bNode) {
+            errors.push({ path: `${cpath}.axis_b_value_ref`, message: `Unknown node id: ${bRef}` });
+          } else if (bNode.type !== "classification_value") {
+            errors.push({ path: `${cpath}.axis_b_value_ref`, message: `Expected classification_value, found "${String(bNode.type)}" at ${bRef}` });
+          }
+          if (aNode && bNode && aNode.type === "classification_value" && bNode.type === "classification_value") {
+            const aAxis = valueToAxis.get(aRef);
+            const bAxis = valueToAxis.get(bRef);
+            if (aAxis && bAxis && aAxis === bAxis) {
+              errors.push({
+                path: cpath,
+                message: `empty_cells references two classification_values from the same axis (${aAxis}); axis_a and axis_b must come from distinct classification_axis parents.`
+              });
+            }
+          }
+          const kind = c.rationale_kind;
+          if (kind !== void 0 && kind !== "structural" && kind !== "ideological" && kind !== "opportunity") {
+            errors.push({
+              path: `${cpath}.rationale_kind`,
+              message: `rationale_kind must be one of 'structural' | 'ideological' | 'opportunity'; got "${String(kind)}".`
+            });
+          }
+        });
+      });
+    }
+  }
+  return { valid: errors.length === 0, errors, warnings };
+}
+function runtimeKind(val) {
+  if (val === null || val === void 0) return null;
+  if (Array.isArray(val)) return "string[]";
+  switch (typeof val) {
+    case "string":
+      return "string";
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "object":
+      return "object";
+    default:
+      return null;
+  }
+}
+function valueMatchesType(defType, val) {
+  const kind = runtimeKind(val);
+  if (kind === null) return true;
+  switch (defType) {
+    case "string":
+      return kind === "string";
+    case "number":
+      return kind === "number";
+    case "boolean":
+      return kind === "boolean";
+    case "string[]":
+      return kind === "string[]";
+    case "object":
+    case "assessment":
+      return kind === "object";
+    default:
+      return true;
+  }
+}
+function describeKind(val) {
+  if (Array.isArray(val)) return "array";
+  return typeof val;
+}
+function validateNodeProperties(node, basePath, warnings) {
+  const type = node.type;
+  if (typeof type !== "string") return;
+  const schema = getPropertySchema(type);
+  if (!schema) return;
+  const props = node.properties;
+  if (!props || typeof props !== "object" || Array.isArray(props)) return;
+  for (const [key, value] of Object.entries(props)) {
+    const def = schema[key];
+    if (!def) continue;
+    if (value === null || value === void 0) continue;
+    if (!valueMatchesType(def.type, value)) {
+      warnings.push({
+        path: `${basePath}.properties.${key}`,
+        message: `Property "${key}" on ${type} should be ${def.type}, got ${describeKind(value)}.`,
+        rule: "property-type"
+      });
+      continue;
+    }
+    if (def.enum && typeof value === "string" && !def.enum.includes(value)) {
+      warnings.push({
+        path: `${basePath}.properties.${key}`,
+        message: `Property "${key}" on ${type} has value "${value}" outside its allowed set: ${def.enum.join(", ")}.`,
+        rule: "property-enum"
+      });
+    }
+  }
+}
+function isUPGDocument(doc) {
+  return validateUPGDocument(doc).valid;
+}
+
+// src/frameworks/canonical.ts
+var UPG_FRAMEWORKS = [
+  {
+    "id": "opportunity-solution-tree",
+    "approach_ids": [
+      "trace"
+    ],
+    "name": "Opportunity Solution Tree",
+    "version": "1.0.0",
+    "description": "Map desired outcomes to opportunities, then branch into solutions and experiments. Ensures every solution traces back to a real user need.",
+    "category": "discovery",
+    "origin": {
+      "type": "practitioner",
+      "attribution": "Teresa Torres",
+      "description": "Introduced in Continuous Discovery Habits. Maps outcomes to opportunities, solutions, and experiments.",
+      "url": "https://www.producttalk.org/opportunity-solution-tree/",
+      "year": 2021,
+      "license": "published_methodology"
+    },
+    "tags": [
+      "discovery",
+      "tree"
+    ],
+    "slots": [
+      {
+        "label": "Root Outcome",
+        "entityTypeId": "outcome",
+        "description": "The desired business or user outcome"
+      },
+      {
+        "label": "Opportunities",
+        "entityTypeId": "opportunity",
+        "description": "User needs, pain points, or desires"
+      },
+      {
+        "label": "Solutions",
+        "entityTypeId": "solution",
+        "description": "Ideas to address each opportunity"
+      },
+      {
+        "label": "Experiments",
+        "entityTypeId": "experiment_run",
+        "description": "Tests to validate each solution"
+      }
+    ],
+    "data": {
+      "entity_types": [
+        {
+          "type": "outcome",
+          "role": "root"
+        },
+        {
+          "type": "opportunity",
           "role": "item"
         },
         {
@@ -13072,7 +13156,7 @@ var UPG_FRAMEWORKS = [
     ],
     "name": "RICE Scoring",
     "version": "1.0.0",
-    "description": "Score features and opportunities by Reach, Impact, Confidence, and Effort to produce a ranked priority list.",
+    "description": "Score features, opportunities, and needs by Reach, Impact, Confidence, and Effort to produce a ranked priority list.",
     "category": "prioritization",
     "origin": {
       "type": "practitioner",
@@ -13090,7 +13174,17 @@ var UPG_FRAMEWORKS = [
       {
         "label": "Items to score",
         "entityTypeId": "feature",
-        "description": "Features, opportunities, or solutions being evaluated"
+        "description": "Features, opportunities, or needs being evaluated"
+      },
+      {
+        "label": "Opportunities to score",
+        "entityTypeId": "opportunity",
+        "description": "Opportunities scored on the same RICE Scoring inputs as features."
+      },
+      {
+        "label": "Needs to score",
+        "entityTypeId": "need",
+        "description": "Needs scored on the same RICE Scoring inputs as features."
       }
     ],
     "data": {
@@ -13098,6 +13192,14 @@ var UPG_FRAMEWORKS = [
         {
           "type": "feature",
           "role": "scored_item"
+        },
+        {
+          "type": "opportunity",
+          "role": "scored_item"
+        },
+        {
+          "type": "need",
+          "role": "scored_item"
         }
       ],
       "required_properties": {
@@ -13138,6 +13240,82 @@ var UPG_FRAMEWORKS = [
             "label": "Effort",
             "description": "How much work is required to build and ship this, on the effort scale?"
           }
+        ],
+        "opportunity": [
+          {
+            "property": "reach",
+            "type": "assessment",
+            "scale_id": "reach_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Reach",
+            "description": "How many users will this impact per quarter?"
+          },
+          {
+            "property": "impact",
+            "type": "assessment",
+            "scale_id": "impact_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Impact",
+            "description": "How much will this impact each user, on the impact scale?"
+          },
+          {
+            "property": "confidence",
+            "type": "assessment",
+            "scale_id": "confidence_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Confidence",
+            "description": "How confident are you in the reach, impact, and effort estimates?"
+          },
+          {
+            "property": "effort",
+            "type": "assessment",
+            "scale_id": "effort_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Effort",
+            "description": "How much work is required to build and ship this, on the effort scale?"
+          }
+        ],
+        "need": [
+          {
+            "property": "reach",
+            "type": "assessment",
+            "scale_id": "reach_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Reach",
+            "description": "How many users will this impact per quarter?"
+          },
+          {
+            "property": "impact",
+            "type": "assessment",
+            "scale_id": "impact_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Impact",
+            "description": "How much will this impact each user, on the impact scale?"
+          },
+          {
+            "property": "confidence",
+            "type": "assessment",
+            "scale_id": "confidence_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Confidence",
+            "description": "How confident are you in the reach, impact, and effort estimates?"
+          },
+          {
+            "property": "effort",
+            "type": "assessment",
+            "scale_id": "effort_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Effort",
+            "description": "How much work is required to build and ship this, on the effort scale?"
+          }
         ]
       },
       "computed_properties": [
@@ -13147,8 +13325,75 @@ var UPG_FRAMEWORKS = [
           "entity_type": "feature",
           "label": "RICE Score",
           "format": "number"
+        },
+        {
+          "property": "rice_score",
+          "expression": "(reach * impact * confidence) / effort",
+          "entity_type": "opportunity",
+          "label": "RICE Score",
+          "format": "number"
+        },
+        {
+          "property": "rice_score",
+          "expression": "(reach * impact * confidence) / effort",
+          "entity_type": "need",
+          "label": "RICE Score",
+          "format": "number"
         }
-      ]
+      ],
+      "scoring_lens": {
+        "applies_to": [
+          "feature",
+          "opportunity",
+          "need"
+        ],
+        "inputs": [
+          {
+            "property": "reach",
+            "type": "assessment",
+            "scale_id": "reach_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Reach",
+            "description": "How many users will this impact per quarter?"
+          },
+          {
+            "property": "impact",
+            "type": "assessment",
+            "scale_id": "impact_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Impact",
+            "description": "How much will this impact each user, on the impact scale?"
+          },
+          {
+            "property": "confidence",
+            "type": "assessment",
+            "scale_id": "confidence_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Confidence",
+            "description": "How confident are you in the reach, impact, and effort estimates?"
+          },
+          {
+            "property": "effort",
+            "type": "assessment",
+            "scale_id": "effort_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Effort",
+            "description": "How much work is required to build and ship this, on the effort scale?"
+          }
+        ],
+        "computed": [
+          {
+            "property": "rice_score",
+            "expression": "(reach * impact * confidence) / effort",
+            "label": "RICE Score",
+            "format": "number"
+          }
+        ]
+      }
     },
     "structure": {
       "pattern": "table"
@@ -15273,7 +15518,7 @@ var UPG_FRAMEWORKS = [
       "entity_types": [
         {
           "type": "team",
-          "role": "scored_item"
+          "role": "item"
         },
         {
           "type": "retrospective",
@@ -15530,6 +15775,16 @@ var UPG_FRAMEWORKS = [
         "label": "Ease",
         "entityTypeId": "feature",
         "description": "How easy is this to implement?"
+      },
+      {
+        "label": "Opportunities to score",
+        "entityTypeId": "opportunity",
+        "description": "Opportunities scored on the same ICE Scoring inputs as features."
+      },
+      {
+        "label": "Needs to score",
+        "entityTypeId": "need",
+        "description": "Needs scored on the same ICE Scoring inputs as features."
       }
     ],
     "data": {
@@ -15545,6 +15800,14 @@ var UPG_FRAMEWORKS = [
         {
           "type": "assumption",
           "role": "item"
+        },
+        {
+          "type": "opportunity",
+          "role": "scored_item"
+        },
+        {
+          "type": "need",
+          "role": "scored_item"
         }
       ],
       "required_properties": {
@@ -15573,6 +15836,58 @@ var UPG_FRAMEWORKS = [
             "label": "Ease",
             "description": "Ease of implementation (1-10)"
           }
+        ],
+        "opportunity": [
+          {
+            "property": "impact",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Impact",
+            "description": "Expected impact on the target metric (1-10)"
+          },
+          {
+            "property": "confidence",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Confidence",
+            "description": "Confidence in the impact estimate (1-10)"
+          },
+          {
+            "property": "ease",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Ease",
+            "description": "Ease of implementation (1-10)"
+          }
+        ],
+        "need": [
+          {
+            "property": "impact",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Impact",
+            "description": "Expected impact on the target metric (1-10)"
+          },
+          {
+            "property": "confidence",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Confidence",
+            "description": "Confidence in the impact estimate (1-10)"
+          },
+          {
+            "property": "ease",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Ease",
+            "description": "Ease of implementation (1-10)"
+          }
         ]
       },
       "computed_properties": [
@@ -15582,8 +15897,63 @@ var UPG_FRAMEWORKS = [
           "entity_type": "feature",
           "label": "ICE Score",
           "format": "number"
+        },
+        {
+          "property": "ice_score",
+          "expression": "impact * confidence * ease",
+          "entity_type": "opportunity",
+          "label": "ICE Score",
+          "format": "number"
+        },
+        {
+          "property": "ice_score",
+          "expression": "impact * confidence * ease",
+          "entity_type": "need",
+          "label": "ICE Score",
+          "format": "number"
         }
-      ]
+      ],
+      "scoring_lens": {
+        "applies_to": [
+          "feature",
+          "opportunity",
+          "need"
+        ],
+        "inputs": [
+          {
+            "property": "impact",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Impact",
+            "description": "Expected impact on the target metric (1-10)"
+          },
+          {
+            "property": "confidence",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Confidence",
+            "description": "Confidence in the impact estimate (1-10)"
+          },
+          {
+            "property": "ease",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Ease",
+            "description": "Ease of implementation (1-10)"
+          }
+        ],
+        "computed": [
+          {
+            "property": "ice_score",
+            "expression": "impact * confidence * ease",
+            "label": "ICE Score",
+            "format": "number"
+          }
+        ]
+      }
     },
     "structure": {
       "pattern": "table"
@@ -15685,6 +16055,11 @@ var UPG_FRAMEWORKS = [
         "label": "Job Size",
         "entityTypeId": "metric",
         "description": "Estimated effort (story points, t-shirt size, or person-weeks)"
+      },
+      {
+        "label": "Opportunities to score",
+        "entityTypeId": "opportunity",
+        "description": "Opportunities scored on the same WSJF (Weighted Shortest Job First) inputs as features."
       }
     ],
     "data": {
@@ -15696,6 +16071,10 @@ var UPG_FRAMEWORKS = [
         {
           "type": "metric",
           "role": "item"
+        },
+        {
+          "type": "opportunity",
+          "role": "scored_item"
         }
       ],
       "required_properties": {
@@ -15732,6 +16111,40 @@ var UPG_FRAMEWORKS = [
             "label": "Job Size",
             "description": "Estimated effort (story points, t-shirt size, or person-weeks)"
           }
+        ],
+        "opportunity": [
+          {
+            "property": "user_value",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "User/Business Value",
+            "description": "Relative value to users and the business if delivered"
+          },
+          {
+            "property": "time_criticality",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Time Criticality",
+            "description": "How much value decays if delivery is delayed (deadlines, competition, seasonal windows)"
+          },
+          {
+            "property": "risk_reduction",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Risk Reduction / Opportunity Enablement",
+            "description": "Value from reducing risk or enabling future opportunities"
+          },
+          {
+            "property": "job_size",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Job Size",
+            "description": "Estimated effort (story points, t-shirt size, or person-weeks)"
+          }
         ]
       },
       "computed_properties": [
@@ -15741,8 +16154,63 @@ var UPG_FRAMEWORKS = [
           "entity_type": "feature",
           "label": "WSJF Score",
           "format": "number"
+        },
+        {
+          "property": "wsjf_score",
+          "expression": "(user_value + time_criticality + risk_reduction) / job_size",
+          "entity_type": "opportunity",
+          "label": "WSJF Score",
+          "format": "number"
         }
-      ]
+      ],
+      "scoring_lens": {
+        "applies_to": [
+          "feature",
+          "opportunity"
+        ],
+        "inputs": [
+          {
+            "property": "user_value",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "User/Business Value",
+            "description": "Relative value to users and the business if delivered"
+          },
+          {
+            "property": "time_criticality",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Time Criticality",
+            "description": "How much value decays if delivery is delayed (deadlines, competition, seasonal windows)"
+          },
+          {
+            "property": "risk_reduction",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Risk Reduction / Opportunity Enablement",
+            "description": "Value from reducing risk or enabling future opportunities"
+          },
+          {
+            "property": "job_size",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Job Size",
+            "description": "Estimated effort (story points, t-shirt size, or person-weeks)"
+          }
+        ],
+        "computed": [
+          {
+            "property": "wsjf_score",
+            "expression": "(user_value + time_criticality + risk_reduction) / job_size",
+            "label": "WSJF Score",
+            "format": "number"
+          }
+        ]
+      }
     },
     "structure": {
       "pattern": "table"
@@ -15815,7 +16283,7 @@ var UPG_FRAMEWORKS = [
     ],
     "name": "Cost of Delay",
     "version": "1.0.0",
-    "description": "Quantify the economic cost of not shipping a feature to drive priority decisions. Combines urgency with value.",
+    "description": "Quantify the economic cost of not shipping a feature or opportunity to drive priority decisions. Combines urgency with value.",
     "category": "prioritization",
     "origin": {
       "type": "practitioner",
@@ -15848,6 +16316,11 @@ var UPG_FRAMEWORKS = [
         "label": "Risk Reduction",
         "entityTypeId": "risk",
         "description": "What risk does this mitigate?"
+      },
+      {
+        "label": "Opportunities to score",
+        "entityTypeId": "opportunity",
+        "description": "Opportunities scored on the same Cost of Delay inputs as features."
       }
     ],
     "data": {
@@ -15867,6 +16340,10 @@ var UPG_FRAMEWORKS = [
         {
           "type": "risk",
           "role": "item"
+        },
+        {
+          "type": "opportunity",
+          "role": "scored_item"
         }
       ],
       "required_properties": {
@@ -15887,6 +16364,24 @@ var UPG_FRAMEWORKS = [
             "label": "Job Size",
             "description": "Weeks of development effort"
           }
+        ],
+        "opportunity": [
+          {
+            "property": "cost_of_delay",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Cost of Delay",
+            "description": "Weekly revenue impact of not shipping"
+          },
+          {
+            "property": "job_size",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Job Size",
+            "description": "Weeks of development effort"
+          }
         ]
       },
       "computed_properties": [
@@ -15896,8 +16391,47 @@ var UPG_FRAMEWORKS = [
           "entity_type": "feature",
           "label": "WSJF Score",
           "format": "number"
+        },
+        {
+          "property": "wsjf_score",
+          "expression": "cost_of_delay / job_size",
+          "entity_type": "opportunity",
+          "label": "WSJF Score",
+          "format": "number"
         }
-      ]
+      ],
+      "scoring_lens": {
+        "applies_to": [
+          "feature",
+          "opportunity"
+        ],
+        "inputs": [
+          {
+            "property": "cost_of_delay",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Cost of Delay",
+            "description": "Weekly revenue impact of not shipping"
+          },
+          {
+            "property": "job_size",
+            "type": "number",
+            "required": true,
+            "scope": "framework",
+            "label": "Job Size",
+            "description": "Weeks of development effort"
+          }
+        ],
+        "computed": [
+          {
+            "property": "wsjf_score",
+            "expression": "cost_of_delay / job_size",
+            "label": "WSJF Score",
+            "format": "number"
+          }
+        ]
+      }
     },
     "structure": {
       "pattern": "table"
@@ -24798,7 +25332,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.8.4";
+var UPG_VERSION = "0.8.7";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -24866,6 +25400,7 @@ export {
   BUSINESS_GROWTH_METRIC_DRIVEN_PLAYBOOK,
   BUSINESS_GTM_GROWTH_PLAYBOOK,
   BUSINESS_MARKETING_AUDIENCE_FIRST_PLAYBOOK,
+  CONTENT_DEPTH_WARNING_RULES,
   DISCOVERY_RESEARCH_VALIDATION_PLAYBOOK,
   ENGINEERING_PLATFORM_PLAYBOOK,
   EXPERIENCE_DESIGN_BRAND_PLAYBOOK,