jprdonnelly/core
1
0
Fork 0
mirror of synced 2025-12-19 18:06:02 -05:00
Code Issues Projects Releases Wiki Activity

Simplify llms.json to single embedded array and update docs

Browse Source 
- Remove _embedded.latest_security_month[] references from all docs
- Update llms.txt, SKILL.md, navigation.md to reflect single latest_patches[] array
- Enhance cve.md with clearer strategy guidance:
  - Decision table: 1-3 months → prev-security walk; 4+ months → year index batch
  - Explicit "Filtering by Version" section using affected_releases
  - Common mistakes for both over/under-engineering
  - Guidance to use fixes[].href directly (no URL fabrication)
- Update queries/*.md files with new patterns

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Rich Lander
2025-12-16 20:19:47 -08:00
parent c5a77ad510
commit 1e4cc94761
9 changed files with 58 additions and 280 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
llms.txt
View File

@@ -16,25 +16,8 @@ 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 |
| `_links` | Navigation to version indexes, timeline, releases |
`_embedded.latest_patches[]` populated by:
```
versions
.Where(v => v.Supported)
.Select(v => v.Patches.MaxBy(p => p.Date))
```
`_embedded.latest_security_month[]` populated by:
```
versions
.Where(v => v.Supported)
.Select(v => timeline
.Where(m => m.HasSecurityPatch(v))
.MaxBy(m => m.Date))
```
| `_embedded.latest_patches[]` | Latest patch per supported version with EOL dates, support status, CVE counts |
| `_links` | Navigation to version indexes, timeline, security months |
## Skills
@@ -62,7 +45,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`
- CVE count in latest patch → `_embedded.latest_patches[]` → `cve_count`
## Navigation Shortcuts

94
release-notes/llms.json
View File

@@ -151,100 +151,6 @@
}
}
}
],
"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"
}
}
}
]
}
}

94
release-notes/llms2.json
View File

@@ -149,100 +149,6 @@
}
}
}
],
"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"
}
}
}
]
}
}

9
release-notes/queries/acceptance.md
View File

@@ -56,7 +56,7 @@ Queries are organized by user task, with 2-3 queries per category. CVE analysis
| M3 | Is there a CRITICAL severity CVE this month? | ≤15 KB | 2 |
**Design validation:**
- `llms.json` embeds `latest_security_month[]` with CVE counts and IDs per version
- `llms.json._links.latest-security-month` points to current security month
- `prev-security` links enable efficient backward traversal (skips non-security releases)
- CVE severity embedded in month/patch indexes (no external fetch required)
@@ -274,7 +274,7 @@ These assumptions underlie the design. If an assumption is incorrect, the design
**Evidence:** LLMs benefit from embedded shortcuts and pre-computed results. They tolerate more frequent updates than CDN-cached production tooling.
**Design response:** `llms.json` provides an AI-optimized entry point with embedded shortcuts (`latest_patches[]`, `latest_security_month[]`). It can be updated more frequently (~12+/year) without impacting the hal-index root. The hal-index maintains strict update discipline; `llms.json` trades stability for convenience.
**Design response:** `llms.json` provides an AI-optimized entry point with embedded shortcuts (`latest_patches[]`). It can be updated more frequently (~12+/year) without impacting the hal-index root. The hal-index maintains strict update discipline; `llms.json` trades stability for convenience.
### A4: Breaking changes and TFMs are upgrade-time concerns
@@ -437,9 +437,8 @@ Each file fully embraces its design point:
- **`llms.json` (7.1 KB)** — Embeds everything an LLM needs for "current state" queries: latest patches, support status, EOL dates, CVE summaries, and navigation links. If an LLM has to make a second fetch for common data, you've paid the 7 KB cost without getting the benefit.
The `llms.json` file embeds two curated arrays:
- `latest_patches[]` — "What's current?" (patch versions, support status, EOL dates, navigation links)
- `latest_security_month[]` — "What's urgent?" (CVE counts, CVE IDs per version)
The `llms.json` file embeds one curated array:
- `latest_patches[]` — "What's current?" (patch versions, support status, EOL dates, CVE counts, navigation links)
Each `latest_patches[]` object includes `release-major` and `latest-sdk` links for direct navigation to version-specific resources. These links are stable (keyed by major version, change ~1x/year).

14
release-notes/queries/metrics.md
View File

@@ -126,12 +126,14 @@ curl -s "$PATCH_HREF" | jq -r '.cve_records[]'
# CVE-2025-55315
```
**llms-index:** The `_embedded.latest_security_month` array provides CVE records directly:
**llms-index:** Follow `latest-security-month` link to get CVE records:
```bash
LLMS="https://raw.githubusercontent.com/dotnet/core/release-index/release-notes/llms.json"
curl -s "$LLMS" | jq -r '._embedded.latest_security_month[] | select(.release == "8.0") | .cve_records[]'
# Get the month index URL
MONTH_URL=$(curl -s "$LLMS" | jq -r '._links["latest-security-month"].href')
curl -s "$MONTH_URL" | jq -r '._embedded.disclosures[] | select(.affected_releases | index("8.0")) | .id'
# CVE-2025-55247
# CVE-2025-55248
# CVE-2025-55315
@@ -189,13 +191,13 @@ curl -s "$PATCH_HREF" | jq -r '._embedded.disclosures[] | select(.cvss_severity
# CVE-2025-55315: .NET Security Feature Bypass Vulnerability (CRITICAL)
```
**llms-index:** Follow the `self` link from `latest_security_month` to get severity details:
**llms-index:** Follow `latest-security-month` link to get severity details:
```bash
LLMS="https://raw.githubusercontent.com/dotnet/core/release-index/release-notes/llms.json"
# Get the month index URL for 8.0's latest security month
MONTH_URL=$(curl -s "$LLMS" | jq -r '._embedded.latest_security_month[] | select(.release == "8.0") | ._links.self.href')
# Get the month index URL
MONTH_URL=$(curl -s "$LLMS" | jq -r '._links["latest-security-month"].href')
curl -s "$MONTH_URL" | jq -r '._embedded.disclosures[] | select(.cvss_severity == "HIGH" or .cvss_severity == "CRITICAL") | "\(.id): \(.title) (\(.cvss_severity))"'
```
@@ -592,7 +594,7 @@ done
- **Completeness:** ❌ The releases-index only provides CVE IDs. To filter by severity, you would need to fetch each CVE from cve.mitre.org.
- **Version-specific traversal:** The hal-index `prev-security` links on patch indexes stay within the major version, efficiently walking through 8.0.21 → 8.0.20 → 8.0.19 etc.
- **The `release` property:** Patch entries include a `release` property (e.g., `"release": "8.0"`) that enables filtering by major version. This is what makes `select(.release == "8.0")` work on embedded patch collections like `_embedded.latest_patches[]` or `_embedded.latest_security_month[]`.
- **The `release` property:** Patch entries include a `release` property (e.g., `"release": "8.0"`) that enables filtering by major version. This is what makes `select(.release == "8.0")` work on embedded patch collections like `_embedded.latest_patches[]`.
- **Use case:** Version-specific security audits ("Is my .NET 8 deployment exposed to any critical vulnerabilities?").
**Winner:** hal-index (**24x smaller**, releases-index cannot answer this query); llms-index is 10% smaller (50 KB vs 55 KB) with direct `latest-security` link

2
release-notes/queries/overview.md
View File

@@ -24,7 +24,7 @@ The tables below show theoretical update frequency based on practice and design,
|------|------|--------------|-------------|
| `llms.json` | 5 KB | ~12+ | AI-optimized entry point with embedded patches and CVE summaries |
The `llms.json` file is designed for AI assistants and can be updated frequently without impacting mission-critical workflows. It embeds `latest_patches` and `latest_security_month` arrays that provide direct answers to common queries.
The `llms.json` file is designed for AI assistants and can be updated frequently without impacting mission-critical workflows. It embeds `latest_patches` with support status and CVE counts that provide direct answers to common queries.
### Hal-Index Files

22
release-notes/skills/SKILL.md
View File

@@ -21,24 +21,8 @@ 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_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:
```
versions
.Where(v => v.Supported)
.Select(v => v.Patches.MaxBy(p => p.Date))
```
`_embedded.latest_security_months[]` populated by:
```
timeline.months
.Where(m => m.Security)
.OrderByDescending(m => m.YearMonth)
.Take(3)
```
| `_embedded.latest_patches[]` | Latest patch per supported version with EOL dates, support status, CVE counts |
| `_links` | Navigation to version indexes, timeline, security months |
## Skills
@@ -66,7 +50,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`
- Recent CVE counts → `_embedded.latest_security_months[]` → `cve_count`, `cve_records`
- CVE count in latest patch → `_embedded.latest_patches[]` → `cve_count`
## Navigation Shortcuts

65
release-notes/skills/cve.md
View File

@@ -6,14 +6,11 @@
1. **Month index `_embedded.disclosures[]` has EVERYTHING**: severity, CVSS score, titles, fix commits. You rarely need `cve.json`.
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
```
llms.json
│
├─► _embedded.latest_security_month[] ─► CVE counts, IDs (no severity)
│
└─► _links["latest-security-month"]
│
@@ -29,49 +26,50 @@ llms.json
## Navigation Strategies
### Strategy 1: `prev-security` Walk (Recent CVEs)
Choose based on time range:
Best for: Last 1-3 months, sequential certainty
| Time Range | Strategy | Why |
|------------|----------|-----|
| 1-3 months | `prev-security` walk | Simple, 2-4 fetches |
| 4+ months or full year | Year index batch | Parallel fetches, fewer turns |
### Strategy 1: `prev-security` Walk
Best for: **1-3 months**
```
llms.json → latest-security-month → prev-security → prev-security...
```
- One fetch per month (sequential)
- Guaranteed to hit only security months
- One fetch per security month (sequential)
- 2-4 total fetches for typical queries
- Simple, follows links exactly
### Strategy 2: Timeline Hierarchy (Historical Analysis)
### Strategy 2: Year Index Batch
Best for: 6-12+ months, broad trend analysis
Best for: **4+ months, full year, or multi-year analysis**
```
llms.json → timeline/index.json
→ [parallel] 2024/index.json + 2025/index.json
→ [parallel] batch fetch cve.json for months with security: true
llms.json → timeline-index → year index
→ [parallel] batch fetch month indexes where 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
- Fetch year index to see all months with `security: true`
- Batch fetch all relevant month indexes in one turn
- 3 turns total regardless of month count
- Much more efficient for broad queries
Use year index `_embedded.months[]` to identify which months have `security: true`, then batch fetch those.
Use `_embedded.months[]` to identify which months have `security: true`, then batch fetch those month indexes (or their `cve-json` links if you need CVSS vectors/CWE).
### Strategy 3: Version Hierarchy (Specific .NET Version)
### Filtering by Version
Best for: "What CVEs affect .NET 8?" or version-specific queries
For "CVEs affecting .NET X", use either strategy above and filter `_embedded.disclosures[]` by `affected_releases`:
```
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
```javascript
disclosures.filter(d => d.affected_releases.includes("8.0"))
```
- 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
Do NOT navigate to the version index (e.g., `8.0/index.json`) for CVE queries—the timeline path with filtering is more efficient.
## Common Queries
@@ -81,12 +79,13 @@ llms.json → _embedded.releases["8.0"]._links.self
2. Follow `_links["latest-security-month"]` → month index
3. Filter `_embedded.disclosures[]` where `cvss_severity == "CRITICAL"`
### CVE history for .NET X (1 + N fetches)
### CVEs for .NET X in last N months (2-4 fetches)
1. Fetch `llms.json`
2. Follow `_links["latest-security-month"]`
3. Walk `_links["prev-security"]` until target date
4. Filter `_embedded.disclosures[]` by `affected_releases`
2. Follow `_links["latest-security-month"]` → month index
3. Filter `_embedded.disclosures[]` where `affected_releases` contains "X.0"
4. Walk `_links["prev-security"]` for N months, filtering each
5. For code fixes: use `fixes[].href` directly (already `.diff` URLs)
### Deep CVE analysis (3 fetches)
@@ -123,10 +122,12 @@ Each `_embedded.disclosures[]` entry contains:
| Mistake | Why It's Wrong |
|---------|----------------|
| Using timeline hierarchy for 1-3 month queries | Overkill—use `prev-security` walk instead |
| Using year index batch for 1-3 month queries | Overkill—use `prev-security` walk instead |
| Using `prev-security` walk for 4+ months | Inefficient—use year index batch with parallel fetches |
| Fetching `cve.json` for severity/CVSS | Month index `_embedded.disclosures[]` already has this data |
| 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 |
| Fabricating GitHub commit URLs | Use `fixes[].href` from disclosures—already formatted as `.diff` URLs |
## Tips

15
release-notes/skills/navigation.md
View File

@@ -9,11 +9,11 @@ Visual map of navigation patterns through the .NET release graph. Use this when
```
llms.json (AI-optimized) index.json (all versions) timeline/index.json (by date)
│ │ │
├─► latest_patches[] ├─► _embedded.releases[] ├─► _embedded.years[]
│ (supported versions) │ (all versions incl EOL) │ └─► _embedded.months[]
│ │ │
└─► latest_security_months[] └─► _links.timeline-index └─► _links.prev-security
(last 3 security months) (walk security history)
└─► latest_patches[] ├─► _embedded.releases[] ├─► _embedded.years[]
(supported versions) │ (all versions incl EOL) │ └─► _embedded.months[]
│ │
└─► _links.timeline-index └─► _links.prev-security
(walk security history)
```
## Flow 1: Supported Version Queries (1-2 fetches)
@@ -34,13 +34,10 @@ llms.json
└─► _links.latest-sdk ─► sdk/index.json ─► DONE (feature bands, downloads)
```
## Flow 2: CVE Queries (1-N fetches)
## Flow 2: CVE Queries (2-N fetches)
```
llms.json
│
├─► _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 ◄────┐
│ │