@unified-product-graph/mcp-server 0.8.4 → 0.8.6

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `@unified-product-graph/mcp-server` are documented in this file. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.8.5] - 2026-06-02
+
+Field-report fast-follow (tester report on 0.8.4).
+
+### Fixed
+- `skill_audit` no longer false-reports skills as out of sync on npm/npx installs. It resolved the canonical source from `process.cwd()/packages/upg-mcp-server/skills` — a monorepo-only path absent in a user's project — so every deployed skill came back unverifiable. It now resolves the skills bundled in the installed package (relative to the module), and treats a symlink to a byte-identical bundle, or a matching copy, as healthy: content match, not deployment method, is the signal.
+
+### Changed
+- The `prioritise` `type_mismatch` hint now points to the framework_exercise escape hatch (`apply_framework` / `upg apply`, then prioritise with `exercise_id`), so scoring a non-target entity type is discoverable.
+
 ## [0.8.4] - 2026-06-02
 
 Framework exercises, with the 0.8.3 launch fix folded in.

package/dist/index.js

@@ -10,7 +10,7 @@ import { UPGFileStore } from "@unified-product-graph/sdk";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import fs2 from "fs";
-import { fileURLToPath } from "url";
+import { fileURLToPath as fileURLToPath2 } from "url";
 import * as path5 from "path";
 import {
   CallToolRequestSchema,
@@ -12334,6 +12334,16 @@ var UPG_FRAMEWORKS = [
         "label": "Items to score",
         "entityTypeId": "feature",
         "description": "Features, opportunities, or solutions 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": {
@@ -12341,6 +12351,14 @@ var UPG_FRAMEWORKS = [
         {
           "type": "feature",
           "role": "scored_item"
+        },
+        {
+          "type": "opportunity",
+          "role": "scored_item"
+        },
+        {
+          "type": "need",
+          "role": "scored_item"
         }
       ],
       "required_properties": {
@@ -12381,6 +12399,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": [
@@ -12390,6 +12484,20 @@ 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"
         }
       ]
     },
@@ -14773,6 +14881,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": {
@@ -14788,6 +14906,14 @@ var UPG_FRAMEWORKS = [
         {
           "type": "assumption",
           "role": "item"
+        },
+        {
+          "type": "opportunity",
+          "role": "scored_item"
+        },
+        {
+          "type": "need",
+          "role": "scored_item"
         }
       ],
       "required_properties": {
@@ -14816,6 +14942,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": [
@@ -14825,6 +15003,20 @@ 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"
         }
       ]
     },
@@ -14928,6 +15120,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": {
@@ -14939,6 +15136,10 @@ var UPG_FRAMEWORKS = [
         {
           "type": "metric",
           "role": "item"
+        },
+        {
+          "type": "opportunity",
+          "role": "scored_item"
         }
       ],
       "required_properties": {
@@ -14975,6 +15176,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": [
@@ -14984,6 +15219,13 @@ 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"
         }
       ]
     },
@@ -15091,6 +15333,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": {
@@ -15110,6 +15357,10 @@ var UPG_FRAMEWORKS = [
         {
           "type": "risk",
           "role": "item"
+        },
+        {
+          "type": "opportunity",
+          "role": "scored_item"
         }
       ],
       "required_properties": {
@@ -15130,6 +15381,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": [
@@ -15139,6 +15408,13 @@ 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"
         }
       ]
     },
@@ -23728,7 +24004,7 @@ function serializePortfolioWithHeader(doc, opts) {
   header.integrity = { algorithm: INTEGRITY_ALGORITHM, body: computeBodyChecksum(doc) };
   return JSON.stringify({ $upg: header, ...body }, null, 2) + "\n";
 }
-var UPG_VERSION = "0.8.4";
+var UPG_VERSION = "0.8.6";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
 var UPG_TYPES_SET = new Set(UPG_TYPES);
@@ -27778,7 +28054,8 @@ var pushToCloud = async (args, ctx) => {
 
 // src/tools/skills.ts
 import { existsSync as existsSync2, lstatSync, readlinkSync, readFileSync as readFileSync2, readdirSync as readdirSync2, realpathSync } from "fs";
-import { join as join5, resolve as resolve2 } from "path";
+import { join as join5, resolve as resolve2, dirname as dirname3 } from "path";
+import { fileURLToPath } from "url";
 function repoRoot() {
   return process.cwd();
 }
@@ -27789,8 +28066,40 @@ function canonicalisePath(p) {
     return p;
   }
 }
+function isSkillsDir(candidate) {
+  try {
+    if (!existsSync2(candidate)) return false;
+    return readdirSync2(candidate, { withFileTypes: true }).some(
+      (e) => (e.isDirectory() || e.isSymbolicLink()) && existsSync2(join5(candidate, e.name, "SKILL.md"))
+    );
+  } catch {
+    return false;
+  }
+}
+function resolveBundledSkillsDir() {
+  let md;
+  try {
+    md = dirname3(fileURLToPath(import.meta.url));
+  } catch {
+    md = process.cwd();
+  }
+  for (const c of [resolve2(md, "..", "skills"), resolve2(md, "..", "..", "skills"), resolve2(md, "skills")]) {
+    if (isSkillsDir(c)) return c;
+  }
+  let dir = md;
+  for (let i = 0; i < 12; i++) {
+    const mono = join5(dir, "packages", "upg-mcp-server", "skills");
+    if (isSkillsDir(mono)) return mono;
+    const parent = dirname3(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
 function sourceSkillsDir() {
-  return resolve2(repoRoot(), "packages/upg-mcp-server/skills");
+  const cwdPath = resolve2(repoRoot(), "packages/upg-mcp-server/skills");
+  if (existsSync2(cwdPath)) return cwdPath;
+  return resolveBundledSkillsDir() ?? cwdPath;
 }
 function deployedSkillsDir() {
   return resolve2(repoRoot(), ".claude/skills");
@@ -27833,6 +28142,21 @@ function auditOne(name) {
   const deployedExists = existsSync2(deployedPath);
   if (!sourceExists) issues.push("Canonical source SKILL.md is missing");
   if (!deployedExists) issues.push("Deployed SKILL.md is missing; run ./scripts/link-skills.sh");
+  let inSync = false;
+  let deployedFrontmatter = null;
+  let deployedFirstHeading = null;
+  if (deployedExists) {
+    const deployedBody = readFileSync2(deployedPath, "utf8");
+    deployedFrontmatter = parseFrontmatter(deployedBody);
+    deployedFirstHeading = firstHeading(deployedBody);
+    if (sourceExists) {
+      const sourceBody = readFileSync2(sourcePath, "utf8");
+      inSync = deployedBody === sourceBody;
+      if (!inSync) {
+        issues.push("Deployed SKILL.md differs from canonical source; symlink is stale or broken");
+      }
+    }
+  }
   let isSymlink = false;
   let symlinkTarget = null;
   if (existsSync2(deployedDir)) {
@@ -27840,32 +28164,17 @@ function auditOne(name) {
     isSymlink = stat.isSymbolicLink();
     if (isSymlink) {
       symlinkTarget = readlinkSync(deployedDir);
-      const targetReal = canonicalisePath(symlinkTarget);
-      const expectedReal = canonicalisePath(sourceDir);
-      if (targetReal !== expectedReal) {
-        issues.push(`Symlink points to ${symlinkTarget}, expected ${sourceDir}`);
+      if (!inSync && sourceExists) {
+        const targetReal = canonicalisePath(symlinkTarget);
+        const expectedReal = canonicalisePath(sourceDir);
+        if (targetReal !== expectedReal) {
+          issues.push(`Symlink points to ${symlinkTarget}, expected ${sourceDir}`);
+        }
       }
-    } else if (deployedExists) {
+    } else if (deployedExists && !inSync) {
       issues.push("Deployed entry is a real directory, not a symlink; stale copy will not pick up source updates; run ./scripts/link-skills.sh");
     }
   }
-  let inSync = false;
-  let deployedFrontmatter = null;
-  let deployedFirstHeading = null;
-  if (deployedExists && sourceExists) {
-    const deployedBody = readFileSync2(deployedPath, "utf8");
-    const sourceBody = readFileSync2(sourcePath, "utf8");
-    inSync = deployedBody === sourceBody;
-    deployedFrontmatter = parseFrontmatter(deployedBody);
-    deployedFirstHeading = firstHeading(deployedBody);
-    if (!inSync) {
-      issues.push("Deployed SKILL.md differs from canonical source; symlink is stale or broken");
-    }
-  } else if (deployedExists) {
-    const deployedBody = readFileSync2(deployedPath, "utf8");
-    deployedFrontmatter = parseFrontmatter(deployedBody);
-    deployedFirstHeading = firstHeading(deployedBody);
-  }
   return {
     name,
     deployed_path: deployedPath,
@@ -29417,7 +29726,7 @@ var SERVER_INSTRUCTIONS = [
 ].join("\n");
 function resolvePackageVersion() {
   try {
-    const here = path5.dirname(fileURLToPath(import.meta.url));
+    const here = path5.dirname(fileURLToPath2(import.meta.url));
     const pkgPath = path5.resolve(here, "..", "package.json");
     const raw = fs2.readFileSync(pkgPath, "utf-8");
     const pkg = JSON.parse(raw);
@@ -29475,7 +29784,7 @@ function createServer(store) {
 
 // src/index.ts
 import { nanoid } from "nanoid";
-import { fileURLToPath as fileURLToPath2 } from "url";
+import { fileURLToPath as fileURLToPath3 } from "url";
 import { realpathSync as realpathSync2 } from "fs";
 async function discoverUPGFile(explicitFile) {
   if (explicitFile) return path6.resolve(explicitFile);
@@ -29649,7 +29958,7 @@ ${lines.join("\n")}
 function isEntrypoint() {
   if (!process.argv[1]) return false;
   try {
-    return realpathSync2(process.argv[1]) === realpathSync2(fileURLToPath2(import.meta.url));
+    return realpathSync2(process.argv[1]) === realpathSync2(fileURLToPath3(import.meta.url));
   } catch {
     return false;
   }