Changes llms.json schema

2025-12-19 18:06:02 -05:00 · 2025-12-16 20:00:51 -08:00
parent fc540d72c5
commit c5a77ad510
6 changed files with 394 additions and 75 deletions
--- a/release-notes/index.json
+++ b/release-notes/index.json
@@ -20,11 +20,6 @@
    "timeline-index": {
      "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/index.json",
      "title": ".NET Release Timeline Index"
-    },
-    "llms-txt": {
-      "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/llms.txt",
-      "title": "READ FIRST: AI navigation guide (links to full reference)",
-      "type": "text/plain"
    }
  },
  "_embedded": {
--- a/release-notes/llms.json
+++ b/release-notes/llms.json
@@ -1,6 +1,8 @@
 {
  "kind": "llms-index",
  "title": ".NET Release Index for AI",
+  "ai_note": "ALWAYS read required_pre_read first. HAL graph\u2014follow _links only, never construct URLs.",
+  "required_pre_read": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/SKILL.md",
  "latest": "10.0",
  "latest_lts": "10.0",
  "latest_year": "2025",
@@ -150,35 +152,10 @@
        }
      }
    ],
-    "latest_security_month": [
+    "latest_security_months": [
      {
-        "release": "10.0",
-        "release_type": "lts",
-        "version": "10.0.0-rc.2",
-        "sdk_version": "10.0.100-rc.2.25502.107",
-        "date": "2025-10-14T00:00:00+00:00",
-        "year": "2025",
        "month": "10",
-        "security": true,
-        "cve_count": 2,
-        "cve_records": [
-          "CVE-2025-55247",
-          "CVE-2025-55315"
-        ],
-        "_links": {
-          "self": {
-            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/2025/10/index.json"
-          }
-        }
-      },
-      {
-        "release": "9.0",
-        "release_type": "sts",
-        "version": "9.0.10",
-        "sdk_version": "9.0.306",
        "date": "2025-10-14T00:00:00+00:00",
-        "year": "2025",
-        "month": "10",
        "security": true,
        "cve_count": 3,
        "cve_records": [
@@ -186,30 +163,85 @@
          "CVE-2025-55315",
          "CVE-2025-55248"
        ],
-        "_links": {
-          "self": {
-            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/2025/10/index.json"
-          }
-        }
-      },
-      {
-        "release": "8.0",
-        "release_type": "lts",
-        "version": "8.0.21",
-        "sdk_version": "8.0.415",
-        "date": "2025-10-14T00:00:00+00:00",
-        "year": "2025",
-        "month": "10",
-        "security": true,
-        "cve_count": 3,
-        "cve_records": [
-          "CVE-2025-55247",
-          "CVE-2025-55315",
-          "CVE-2025-55248"
+        "latest_release": "10.0",
+        "releases": [
+          "10.0",
+          "9.0",
+          "8.0"
+        ],
+        "runtime_patches": [
+          "10.0.0-rc.2",
+          "9.0.10",
+          "8.0.21"
        ],
        "_links": {
          "self": {
            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/2025/10/index.json"
+          },
+          "cve-json": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/2025/10/cve.json",
+            "title": "CVE records (JSON)",
+            "type": "application/json"
+          }
+        }
+      },
+      {
+        "month": "06",
+        "date": "2025-06-10T00:00:00+00:00",
+        "security": true,
+        "cve_count": 1,
+        "cve_records": [
+          "CVE-2025-30399"
+        ],
+        "latest_release": "10.0",
+        "releases": [
+          "10.0",
+          "9.0",
+          "8.0"
+        ],
+        "runtime_patches": [
+          "10.0.0-preview.5",
+          "9.0.6",
+          "8.0.17"
+        ],
+        "_links": {
+          "self": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/2025/06/index.json"
+          },
+          "cve-json": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/2025/06/cve.json",
+            "title": "CVE records (JSON)",
+            "type": "application/json"
+          }
+        }
+      },
+      {
+        "month": "05",
+        "date": "2025-05-13T00:00:00+00:00",
+        "security": true,
+        "cve_count": 1,
+        "cve_records": [
+          "CVE-2025-26646"
+        ],
+        "latest_release": "10.0",
+        "releases": [
+          "10.0",
+          "9.0",
+          "8.0"
+        ],
+        "runtime_patches": [
+          "10.0.0-preview.4",
+          "9.0.5",
+          "8.0.16"
+        ],
+        "_links": {
+          "self": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/2025/05/index.json"
+          },
+          "cve-json": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/2025/05/cve.json",
+            "title": "CVE records (JSON)",
+            "type": "application/json"
          }
        }
      }
--- a/release-notes/llms2.json
+++ b/release-notes/llms2.json
@@ -0,0 +1,248 @@
+{
+  "kind": "llms-index",
+  "title": ".NET Release Index for AI",
+  "latest": "10.0",
+  "latest_lts": "10.0",
+  "latest_year": "2025",
+  "releases": [
+    "10.0",
+    "9.0",
+    "8.0"
+  ],
+  "_links": {
+    "self": {
+      "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/llms.json"
+    },
+    "latest": {
+      "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/10.0/index.json",
+      "title": ".NET 10.0"
+    },
+    "latest-lts": {
+      "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/10.0/index.json",
+      "title": ".NET 10.0 (LTS)"
+    },
+    "latest-month": {
+      "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/2025/12/index.json",
+      "title": "2025-12"
+    },
+    "latest-security-month": {
+      "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/2025/10/index.json",
+      "title": "2025-10"
+    },
+    "latest-year": {
+      "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/2025/index.json",
+      "title": "2025"
+    },
+    "releases-index": {
+      "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/index.json",
+      "title": ".NET Release Index"
+    },
+    "timeline-index": {
+      "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/index.json",
+      "title": ".NET Release Timeline Index"
+    }
+  },
+  "_embedded": {
+    "latest_patches": [
+      {
+        "version": "10.0.1",
+        "release": "10.0",
+        "release_type": "lts",
+        "date": "2025-12-09T00:00:00+00:00",
+        "year": "2025",
+        "month": "12",
+        "security": false,
+        "cve_count": 0,
+        "support_phase": "active",
+        "supported": true,
+        "eol_date": "2028-11-14",
+        "sdk_version": "10.0.101",
+        "_links": {
+          "self": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/10.0/10.0.1/index.json"
+          },
+          "latest-security": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/10.0/preview/rc2/index.json",
+            "title": "10.0.0-rc.2"
+          },
+          "release-major": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/10.0/index.json",
+            "title": ".NET 10.0"
+          },
+          "latest-sdk": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/10.0/sdk/index.json",
+            "title": ".NET 10.0 SDK Index"
+          },
+          "release-manifest": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/10.0/manifest.json",
+            "title": ".NET 10.0 Manifest"
+          }
+        }
+      },
+      {
+        "version": "9.0.11",
+        "release": "9.0",
+        "release_type": "sts",
+        "date": "2025-11-19T00:00:00+00:00",
+        "year": "2025",
+        "month": "11",
+        "security": false,
+        "cve_count": 0,
+        "support_phase": "active",
+        "supported": true,
+        "eol_date": "2026-11-10",
+        "sdk_version": "9.0.308",
+        "_links": {
+          "self": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/9.0/9.0.11/index.json"
+          },
+          "latest-security": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/9.0/9.0.10/index.json",
+            "title": "9.0.10"
+          },
+          "release-major": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/9.0/index.json",
+            "title": ".NET 9.0"
+          },
+          "latest-sdk": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/9.0/sdk/index.json",
+            "title": ".NET 9.0 SDK Index"
+          },
+          "release-manifest": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/9.0/manifest.json",
+            "title": ".NET 9.0 Manifest"
+          }
+        }
+      },
+      {
+        "version": "8.0.22",
+        "release": "8.0",
+        "release_type": "lts",
+        "date": "2025-11-11T00:00:00+00:00",
+        "year": "2025",
+        "month": "11",
+        "security": false,
+        "cve_count": 0,
+        "support_phase": "active",
+        "supported": true,
+        "eol_date": "2026-11-10",
+        "sdk_version": "8.0.416",
+        "_links": {
+          "self": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/8.0/8.0.22/index.json"
+          },
+          "latest-security": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/8.0/8.0.21/index.json",
+            "title": "8.0.21"
+          },
+          "release-major": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/8.0/index.json",
+            "title": ".NET 8.0"
+          },
+          "latest-sdk": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/8.0/sdk/index.json",
+            "title": ".NET 8.0 SDK Index"
+          },
+          "release-manifest": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/8.0/manifest.json",
+            "title": ".NET 8.0 Manifest"
+          }
+        }
+      }
+    ],
+    "latest_security_months": [
+      {
+        "month": "10",
+        "date": "2025-10-14T00:00:00+00:00",
+        "security": true,
+        "cve_count": 3,
+        "cve_records": [
+          "CVE-2025-55247",
+          "CVE-2025-55315",
+          "CVE-2025-55248"
+        ],
+        "latest_release": "10.0",
+        "releases": [
+          "10.0",
+          "9.0",
+          "8.0"
+        ],
+        "runtime_patches": [
+          "10.0.0-rc.2",
+          "9.0.10",
+          "8.0.21"
+        ],
+        "_links": {
+          "self": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/2025/10/index.json"
+          },
+          "cve-json": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/2025/10/cve.json",
+            "title": "CVE records (JSON)",
+            "type": "application/json"
+          }
+        }
+      },
+      {
+        "month": "06",
+        "date": "2025-06-10T00:00:00+00:00",
+        "security": true,
+        "cve_count": 1,
+        "cve_records": [
+          "CVE-2025-30399"
+        ],
+        "latest_release": "10.0",
+        "releases": [
+          "10.0",
+          "9.0",
+          "8.0"
+        ],
+        "runtime_patches": [
+          "10.0.0-preview.5",
+          "9.0.6",
+          "8.0.17"
+        ],
+        "_links": {
+          "self": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/2025/06/index.json"
+          },
+          "cve-json": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/2025/06/cve.json",
+            "title": "CVE records (JSON)",
+            "type": "application/json"
+          }
+        }
+      },
+      {
+        "month": "05",
+        "date": "2025-05-13T00:00:00+00:00",
+        "security": true,
+        "cve_count": 1,
+        "cve_records": [
+          "CVE-2025-26646"
+        ],
+        "latest_release": "10.0",
+        "releases": [
+          "10.0",
+          "9.0",
+          "8.0"
+        ],
+        "runtime_patches": [
+          "10.0.0-preview.4",
+          "9.0.5",
+          "8.0.16"
+        ],
+        "_links": {
+          "self": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/2025/05/index.json"
+          },
+          "cve-json": {
+            "href": "https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/timeline/2025/05/cve.json",
+            "title": "CVE records (JSON)",
+            "type": "application/json"
+          }
+        }
+      }
+    ]
+  }
+}
--- a/release-notes/skills/SKILL.md
+++ b/release-notes/skills/SKILL.md
@@ -22,7 +22,7 @@ https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-n
 | Property | Contains |
 |----------|----------|
 | `_embedded.latest_patches[]` | Latest patch per supported version with EOL dates, support status |
-| `_embedded.latest_security_month[]` | Most recent security month per supported version with CVE IDs |
+| `_embedded.latest_security_months[]` | Last 3 security months (most recent first) with CVE IDs, releases, patches |
 | `_links` | Navigation to version indexes, timeline, releases |

 `_embedded.latest_patches[]` populated by:
@@ -32,13 +32,12 @@ versions
    .Select(v => v.Patches.MaxBy(p => p.Date))
 ```

-`_embedded.latest_security_month[]` populated by:
+`_embedded.latest_security_months[]` populated by:
 ```
-versions
-    .Where(v => v.Supported)
-    .Select(v => timeline
-        .Where(m => m.HasSecurityPatch(v))
-        .MaxBy(m => m.Date))
+timeline.months
+    .Where(m => m.Security)
+    .OrderByDescending(m => m.YearMonth)
+    .Take(3)
 ```

 ## Skills
@@ -67,7 +66,7 @@ These are answered directly from `llms.json`:

 - Latest patch for .NET X → `_embedded.latest_patches[]` filter by `release`
 - Is .NET X supported? → `_embedded.latest_patches[]` → `supported`, `eol_date`
- CVE count this month → `_embedded.latest_security_month[]` → `cve_count`
+- Recent CVE counts → `_embedded.latest_security_months[]` → `cve_count`, `cve_records`

 ## Navigation Shortcuts

--- a/release-notes/skills/cve.md
+++ b/release-notes/skills/cve.md
@@ -5,7 +5,7 @@
 ## Quick Rules

 1. **Month index `_embedded.disclosures[]` has EVERYTHING**: severity, CVSS score, titles, fix commits. You rarely need `cve.json`.
-2. **Use `latest-security-month` → `prev-security` chain**: Don't navigate through timeline year indexes.
+2. **Choose your strategy by query scope**: `prev-security` walk for recent CVEs, timeline hierarchy for historical analysis (see below).
 3. `_embedded.latest_security_month[]` in llms.json has **counts and IDs only** — fetch the month index for details.

 ## Navigation Flow
@@ -27,6 +27,52 @@ llms.json
            └─► _links["prev-security"] ─► previous security month
 ```

+## Navigation Strategies
+
+### Strategy 1: `prev-security` Walk (Recent CVEs)
+
+Best for: Last 1-3 months, sequential certainty
+
+```
+llms.json → latest-security-month → prev-security → prev-security...
+```
+
+- One fetch per month (sequential)
+- Guaranteed to hit only security months
+- Simple, follows links exactly
+
+### Strategy 2: Timeline Hierarchy (Historical Analysis)
+
+Best for: 6-12+ months, broad trend analysis
+
+```
+llms.json → timeline/index.json
+         → [parallel] 2024/index.json + 2025/index.json
+         → [parallel] batch fetch cve.json for months with security: true
+```
+
+- Batch year indexes in one turn
+- Batch multiple cve.json files in one turn
+- 3-4 turns total vs N+1 for sequential walk
+- Much more token-efficient for broad queries
+
+Use year index `_embedded.months[]` to identify which months have `security: true`, then batch fetch those.
+
+### Strategy 3: Version Hierarchy (Specific .NET Version)
+
+Best for: "What CVEs affect .NET 8?" or version-specific queries
+
+```
+llms.json → _embedded.releases["8.0"]._links.self
+         → 8.0/index.json → find security patches in _embedded.releases[]
+         → [parallel] batch fetch patch index.json + timeline cve.json
+```
+
+- Go directly to the version you care about
+- Patch indexes show which releases were security updates
+- Can parallel fetch patch details and CVE data
+- Most efficient when query targets a single .NET version
+
 ## Common Queries

 ### Critical CVEs this month (2 fetches)
@@ -77,9 +123,10 @@ Each `_embedded.disclosures[]` entry contains:

 | Mistake | Why It's Wrong |
 |---------|----------------|
-| Fetching `timeline/index.json` or year indexes | Use `latest-security-month` from llms.json, then walk `prev-security` |
+| Using timeline hierarchy for 1-3 month queries | Overkill—use `prev-security` walk instead |
 | Fetching `cve.json` for severity/CVSS | Month index `_embedded.disclosures[]` already has this data |
-| Constructing URLs like `2024/10/cve.json` | URL fabrication—always follow `_links` |
+| Constructing month URLs without checking year index | Always check `_embedded.months[]` for `security: true` first |
+| Fabricating intermediate month URLs | Trust `prev-security` links—they skip non-security months automatically |

 ## Tips

--- a/release-notes/skills/navigation.md
+++ b/release-notes/skills/navigation.md
@@ -12,8 +12,8 @@ llms.json (AI-optimized)          index.json (all versions)       timeline/index
     ├─► latest_patches[]               ├─► _embedded.releases[]         ├─► _embedded.years[]
     │   (supported versions)           │   (all versions incl EOL)      │   └─► _embedded.months[]
     │                                  │                                │
-     └─► latest_security_month[]        └─► _links.timeline-index        └─► _links.prev-security
-         (current CVE summary)                                               (walk security history)
+     └─► latest_security_months[]       └─► _links.timeline-index        └─► _links.prev-security
+         (last 3 security months)                                            (walk security history)
 ```

 ## Flow 1: Supported Version Queries (1-2 fetches)
@@ -39,18 +39,16 @@ llms.json
 ```
 llms.json
    │
-    ├─► _embedded.latest_security_month[] ─► DONE (CVE IDs and counts only)
+    ├─► _embedded.latest_security_months[] ─► DONE (last 3 months: CVE IDs, releases, patches)
+    │       └─► each entry has _links.cve-json for full CVE details
    │
-    └─► _links.latest-security-month
-            │
-            ▼
-        month/index.json ◄──────────────────┐
-            │                               │
-            ├─► _embedded.disclosures[] ────│─► DONE (severity, titles, fixes)
-            │                               │
-            ├─► _links.cve-json ───────────►│   cve.json ─► DONE (CVSS vectors, CWE, packages)
-            │                               │
-            └─► _links.prev-security ───────┘   (repeat for history)
+    └─► _links.latest-security-month ─► month/index.json ◄────┐
+            │                                                 │
+            ├─► _embedded.disclosures[] ─► DONE (severity)    │
+            │                                                 │
+            ├─► _links.cve-json ─► cve.json (CVSS, CWE)       │
+            │                                                 │
+            └─► _links.prev-security ─────────────────────────┘ (walk history)
 ```

 ## Flow 3: EOL Version Queries (3-5 fetches)