@unified-product-graph/core 0.9.16 → 0.9.18

package/CHANGELOG.md

@@ -7,6 +7,38 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.9.18] - 2026-06-11
+
+**The CLI help stops drifting, and an unknown `tree` filter stops lying.** The CLI rendered `--help` from a hand-maintained table divorced from each command's own option definitions, so adding a flag silently left its help stale (that is how `tree --pattern` shipped undocumented in 0.9.17). Separately, `upg tree <unknown>` quietly rendered the whole graph mislabeled as the filter. Both are now structural.
+
+### Added
+- **A help-drift guard.** The command registry is now a single source of truth that the program, the help-safety test, and a new drift test all iterate. The guard asserts that every registered command has a help topic, every long option it declares is documented, and every subcommand is mentioned, so a new command or flag cannot escape help coverage.
+
+### Fixed
+- **Help is back in sync with the commands.** Documented the options the guard flagged across eleven commands: `context --summary`, `verify --no-content-depth`, `query --edge-include` / `--limit`, `prioritise --framework` (which is required), `move --old-edge`, `dedupe --type` / `--dry-run`, `diff --stat`, `gaps --domain`, `import --output` / `--yes`, `init --file` / `--yes`, `install-skills --mode` / `--list` / `--remove`, and `score --slot-role`. The `spec` help now enumerates its full noun catalogue.
+- **`upg tree <unknown-filter>` errors (exit 3)** instead of silently rendering the whole graph under a wrong label. A valid entity type with no instances reports cleanly, and filtering by a domain id is now actually implemented (the help had always claimed it).
+
+No entity, domain, region, playbook, framework, edge, or tool-count change (entities 315, edges 980, local tools 121). The work is entirely in the CLI.
+
+---
+
+## [0.9.17] - 2026-06-11
+
+**CLI-next: the CLI catches up to the spec, the tree learns its frameworks, and ordering finally means something.** The `upg` CLI had frozen at the 0.8.x command set while the MCP tool surface grew to 121; its `list`/`tree` ordered lexically and re-rendered shared subtrees into noise. This release closes all of it, and folds in the `get_tree` pattern-definition fixes from a post-ship report on a real 304-node graph.
+
+### Added
+- **Meaning-aware node ordering** (`compareNodesWithinType`, SDK). The intra-type sort ladder: explicit order field (`<type>_order` / order / sequence / ...) -> semantic version (title or `version`) -> lifecycle/status phase position -> `created_at` -> numeric-aware locale. A release series now reads `v5.0.0, v5.1.0, ... v5.9.0, v5.10.0, ... v5.30.0, v6.0.0` instead of the lexical `v5.1.0, v5.10.0, ... v5.2.0`. `list`/`tree` and `get_tree` share it.
+- **DAG-honest tree assembly.** A UPG graph is a DAG; a multi-parent node now renders its subtree ONCE and appears as a `shared` reference under its other parents, in both `get_tree` (`stats.shared_refs`) and the CLI `tree` (`↗ shown above`). Nothing is silently dropped, nothing re-explodes, cycles terminate. `assembleTree` moved to the SDK so the local server, cloud server, and CLI share one implementation.
+- **A `delivery` tree pattern** for the roadmap/release region; `UPG_TREE_PATTERNS` is now 8.
+- **CLI tool-parity surface**: the full 0.9.x MCP surface as commands. New groups `spec` (offline catalogue browser, 36 nouns), `query`, `registry`, `portfolio`, `area`, `migrate`; `tree --pattern <id>` (framework-aware trees via the shared assembler); and singletons `move`, `disconnect`, `dedupe`, `clone`, `context`, `log`, `prioritise`, `sync status`, `product update`, `batch`. Six MCP tools are deliberately not mirrored (recorded by ADR): the agent-cognitive `plan`/`reflect`/`trace`, the remote-mutating `apply_pull_changeset`/`push_to_cloud`, and the skill-dev `skill_audit`.
+
+### Changed
+- **`get_tree` pattern definitions corrected (G1-G7)** against the real graph: child slots gain a `required` flag so gaps flag only genuinely-missing required children (no more ~50 false `epic` gaps); the `strategy` pattern reaches the polymorphically-parented bets and auto-flags a bet with no initiative; `okr` extends to the `metric` leaf and `ost` to `hypothesis`/`experiment_plan`; `validation` accepts `experiment` or `experiment_run`; anchor selection picks the candidate that surfaces the most of the pattern, not the first non-empty.
+
+No entity, domain, region, playbook, framework, or local-tool count change (entities 315, edges 980, local tools 121, regions 11, frameworks 46). The work is in the CLI, the SDK, and the tree presentation layer.
+
+---
+
 ## [0.9.16] - 2026-06-11
 
 **get_tree reaches the cloud, the show-tree skill calls it, and the three "area" taxonomies get a documented cross-walk.** 0.9.15 shipped `get_tree` local-only and left the show-tree skill on its interim hardcoded chains; this release finishes the loop and closes the deferred A4 introspection gap.

package/dist/index.cjs

@@ -18408,13 +18408,13 @@ function validateFrameworkScores(nodes, edges, warnings) {
     const divisors = divisorInputs(framework);
     const path = `$.edges[${i}].properties`;
     const scoreObj = score;
-    for (const req of requirements) {
-      const value = scoreObj[req.property];
+    for (const req2 of requirements) {
+      const value = scoreObj[req2.property];
       if (value === void 0 || value === null) continue;
-      const finding = checkScoreValue(req, value, divisors.has(req.property), framework.id);
+      const finding = checkScoreValue(req2, value, divisors.has(req2.property), framework.id);
       if (finding) {
         warnings.push({
-          path: `${path}.${req.property}`,
+          path: `${path}.${req2.property}`,
           message: finding,
           rule: "framework-score"
         });
@@ -18434,58 +18434,58 @@ function divisorInputs(framework) {
   return out;
 }
 var EMPTY_STRING_SET = /* @__PURE__ */ new Set();
-function checkScoreValue(req, value, isDivisor, frameworkId) {
-  switch (req.type) {
+function checkScoreValue(req2, value, isDivisor, frameworkId) {
+  switch (req2.type) {
     case "enum": {
-      const allowed = req.enum_values ?? [];
+      const allowed = req2.enum_values ?? [];
       if (typeof value !== "string") {
-        return `${frameworkId} score "${req.property}" must be one of ${allowed.join(", ")}; got ${describeKind(value)}.`;
+        return `${frameworkId} score "${req2.property}" must be one of ${allowed.join(", ")}; got ${describeKind(value)}.`;
       }
       if (allowed.length > 0 && !allowed.includes(value)) {
-        return `${frameworkId} score "${req.property}" has value "${value}" outside its allowed set: ${allowed.join(", ")}.`;
+        return `${frameworkId} score "${req2.property}" has value "${value}" outside its allowed set: ${allowed.join(", ")}.`;
       }
       return null;
     }
     case "assessment": {
       const num = numericScore(value);
       if (num === null) {
-        return `${frameworkId} score "${req.property}" must be a number; got ${describeKind(value)}.`;
+        return `${frameworkId} score "${req2.property}" must be a number; got ${describeKind(value)}.`;
       }
-      const scale = req.scale_id ? getScale(req.scale_id) : void 0;
+      const scale = req2.scale_id ? getScale(req2.scale_id) : void 0;
       if (scale) {
         if (num < scale.min || num > scale.max) {
-          return `${frameworkId} score "${req.property}" is ${num}, outside the ${req.scale_id} scale range [${scale.min}, ${scale.max}].`;
+          return `${frameworkId} score "${req2.property}" is ${num}, outside the ${req2.scale_id} scale range [${scale.min}, ${scale.max}].`;
         }
       } else if (num <= 0) {
-        return `${frameworkId} score "${req.property}" must be greater than 0; got ${num}.`;
+        return `${frameworkId} score "${req2.property}" must be greater than 0; got ${num}.`;
       }
       if (isDivisor && num === 0) {
-        return `${frameworkId} score "${req.property}" must not be 0 (it is a divisor in the framework's formula).`;
+        return `${frameworkId} score "${req2.property}" must not be 0 (it is a divisor in the framework's formula).`;
       }
       return null;
     }
     case "number": {
       const num = numericScore(value);
       if (num === null) {
-        return `${frameworkId} score "${req.property}" must be a number; got ${describeKind(value)}.`;
+        return `${frameworkId} score "${req2.property}" must be a number; got ${describeKind(value)}.`;
       }
       if (isDivisor && num === 0) {
-        return `${frameworkId} score "${req.property}" must not be 0 (it is a divisor in the framework's formula).`;
+        return `${frameworkId} score "${req2.property}" must not be 0 (it is a divisor in the framework's formula).`;
       }
       if (num < 0) {
-        return `${frameworkId} score "${req.property}" must not be negative; got ${num}.`;
+        return `${frameworkId} score "${req2.property}" must not be negative; got ${num}.`;
       }
       return null;
     }
     case "boolean": {
       if (typeof value !== "boolean") {
-        return `${frameworkId} score "${req.property}" must be a boolean; got ${describeKind(value)}.`;
+        return `${frameworkId} score "${req2.property}" must be a boolean; got ${describeKind(value)}.`;
       }
       return null;
     }
     case "string": {
       if (typeof value !== "string") {
-        return `${frameworkId} score "${req.property}" must be a string; got ${describeKind(value)}.`;
+        return `${frameworkId} score "${req2.property}" must be a string; got ${describeKind(value)}.`;
       }
       return null;
     }
@@ -19871,33 +19871,38 @@ function buildTypeAliases() {
 var UPG_TYPE_ALIASES = buildTypeAliases();
 
 // src/presentation/tree-patterns.ts
+var req = (type) => ({ type, required: true });
+var opt = (type) => ({ type });
 var UPG_TREE_PATTERNS = [
   {
     id: "ost",
     label: "Opportunity Solution Tree",
-    description: "A desired outcome branching into the opportunities under it and the solutions that address them (Teresa Torres).",
+    description: "A desired outcome branching into the opportunities under it, the solutions that address them, and the hypotheses + experiment plans that validate them (Teresa Torres).",
     framework_id: "opportunity-solution-tree",
     anchor_type: "outcome",
     fallback_anchors: ["desired_outcome", "opportunity"],
     child_map: {
-      outcome: ["opportunity"],
-      desired_outcome: ["opportunity"],
-      opportunity: ["solution"]
+      outcome: [req("opportunity")],
+      desired_outcome: [req("opportunity")],
+      opportunity: [req("solution")],
+      solution: [opt("hypothesis")],
+      hypothesis: [opt("experiment_plan")]
     },
-    natural_depth: 3
+    natural_depth: 5
   },
   {
     id: "okr",
     label: "Objectives and Key Results",
-    description: "Strategic themes containing objectives, each measured by its key results (John Doerr).",
+    description: "Strategic themes containing objectives, each measured by its key results and the metric that quantifies them (John Doerr).",
     framework_id: "okr-framework",
     anchor_type: "strategic_theme",
     fallback_anchors: ["objective"],
     child_map: {
-      strategic_theme: ["objective"],
-      objective: ["key_result"]
+      strategic_theme: [req("objective")],
+      objective: [req("key_result")],
+      key_result: [opt("metric")]
     },
-    natural_depth: 3
+    natural_depth: 4
   },
   {
     id: "user",
@@ -19906,54 +19911,55 @@ var UPG_TREE_PATTERNS = [
     anchor_type: "persona",
     fallback_anchors: ["job"],
     child_map: {
-      persona: ["job", "need", "desired_outcome"],
-      job: ["need", "desired_outcome"]
+      persona: [req("job"), opt("need"), opt("desired_outcome")],
+      job: [opt("need"), opt("desired_outcome")]
     },
     natural_depth: 3
   },
   {
     id: "product",
     label: "Product breakdown",
-    description: "The product organised into feature areas, then features, epics, and user stories.",
+    description: "The product organised into feature areas, then features, and the optional epic + user story tiers beneath them.",
     anchor_type: "product",
     fallback_anchors: ["feature_area", "feature"],
     child_map: {
-      product: ["feature_area"],
-      feature_area: ["feature"],
-      feature: ["epic"],
-      epic: ["user_story"]
+      product: [opt("feature_area")],
+      feature_area: [req("feature")],
+      feature: [opt("epic")],
+      epic: [opt("user_story")]
     },
     natural_depth: 5
   },
   {
     id: "validation",
     label: "Validation chain",
-    description: "A hypothesis through its experiment plan, experiment, run, and the learning it produced.",
+    description: "A hypothesis through its experiment plan, the experiment (or its runs), and the learning it produced.",
     framework_id: "build-measure-learn",
     anchor_type: "hypothesis",
     fallback_anchors: ["experiment_plan", "experiment"],
     child_map: {
-      hypothesis: ["experiment_plan"],
-      experiment_plan: ["experiment"],
-      experiment: ["experiment_run"],
-      experiment_run: ["learning"]
+      hypothesis: [req("experiment_plan")],
+      experiment_plan: [req("experiment"), req("experiment_run")],
+      experiment: [opt("experiment_run"), opt("learning")],
+      experiment_run: [opt("learning")]
     },
     natural_depth: 5
   },
   {
     id: "strategy",
     label: "Strategy cascade",
-    description: "Vision and mission into the strategic themes (bets), the initiatives that pursue them, and the outcomes they drive. Themes anchor on vision OR the product, whichever the graph wired.",
+    description: "Vision and mission into the strategic themes (bets), the initiatives that pursue them, and the outcomes they drive. Themes are polymorphically parented: they hang off vision, the product, or a strategic pillar, whichever the graph wired.",
     anchor_type: "vision",
     fallback_anchors: ["product", "strategic_theme"],
     child_map: {
-      vision: ["mission", "strategic_theme"],
-      product: ["strategic_theme"],
-      mission: ["strategic_theme"],
-      strategic_theme: ["initiative"],
-      initiative: ["outcome"]
+      vision: [opt("mission"), opt("strategic_theme")],
+      mission: [opt("strategic_pillar")],
+      strategic_pillar: [opt("strategic_theme")],
+      product: [opt("strategic_theme")],
+      strategic_theme: [req("initiative")],
+      initiative: [opt("outcome")]
     },
-    natural_depth: 4
+    natural_depth: 5
   },
   {
     id: "feature_areas",
@@ -19962,9 +19968,26 @@ var UPG_TREE_PATTERNS = [
     anchor_type: "feature_area",
     fallback_anchors: ["feature"],
     child_map: {
-      feature_area: ["feature"]
+      feature_area: [opt("feature")]
     },
     natural_depth: 2
+  },
+  {
+    id: "delivery",
+    label: "Delivery roadmap",
+    description: "How product work is scheduled and shipped: the roadmap and its themes/items, the releases they schedule, and the features (with optional epic + user story tiers) they deliver.",
+    anchor_type: "roadmap",
+    fallback_anchors: ["product", "release"],
+    child_map: {
+      product: [opt("roadmap"), opt("release")],
+      roadmap: [opt("roadmap_theme"), opt("roadmap_item"), opt("release")],
+      roadmap_theme: [opt("feature")],
+      roadmap_item: [opt("feature")],
+      release: [opt("feature")],
+      feature: [opt("epic")],
+      epic: [opt("user_story")]
+    },
+    natural_depth: 5
   }
 ];
 var UPG_TREE_PATTERNS_BY_ID = Object.fromEntries(
@@ -28277,7 +28300,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.9.16";
+var UPG_VERSION = "0.9.18";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();