@blamejs/exceptd-skills 0.10.1 → 0.10.3

package/orchestrator/index.js

@@ -161,8 +161,13 @@ Examples:
 // --- command implementations ---
 
 async function runScan() {
-  console.log('[orchestrator] Scanning environment...\n');
+  const jsonOut = process.argv.includes('--json');
+  if (!jsonOut) console.log('[orchestrator] Scanning environment...\n');
   const result = await scan();
+  if (jsonOut) {
+    process.stdout.write(JSON.stringify(result) + '\n');
+    return result;
+  }
 
   console.log('Host:', JSON.stringify(result.host, null, 2));
   console.log('\nFindings by domain:');
@@ -190,10 +195,16 @@ async function runScan() {
 }
 
 async function runDispatch() {
-  console.log('[orchestrator] Scanning then dispatching...\n');
+  const jsonOut = process.argv.includes('--json');
+  if (!jsonOut) console.log('[orchestrator] Scanning then dispatching...\n');
   const scanResult = await scan();
   const plan = dispatch(scanResult.findings);
 
+  if (jsonOut) {
+    process.stdout.write(JSON.stringify({ scan: scanResult, dispatch: plan }) + '\n');
+    return plan;
+  }
+
   console.log(`Dispatch plan — ${plan.plan.length} skills to invoke:\n`);
 
   for (const item of plan.plan) {
@@ -233,7 +244,8 @@ function runSkillContext(skillName) {
 
   const context = getSkillContext(skillName);
   if (!context) {
-    console.error(`Skill not found: ${skillName}`);
+    // Unified error shape across the CLI surface — see v0.10.3 bug #18.
+    process.stderr.write(JSON.stringify({ ok: false, error: `Skill not found: ${skillName}`, verb: "skill", hint: "Run `exceptd plan` or check skills/ for available skill IDs." }) + "\n");
     process.exit(1);
   }
 
@@ -266,9 +278,15 @@ function runPipeline(triggerType, payload) {
 }
 
 function runCurrency() {
+  const jsonOut = process.argv.includes('--json');
   const result = runCurrencyNow();
   const { currency_report, action_required, critical_count } = currencyCheck();
 
+  if (jsonOut) {
+    process.stdout.write(JSON.stringify({ currency_report, action_required, critical_count, generated_at: new Date().toISOString() }) + '\n');
+    return;
+  }
+
   console.log(`\nSkill currency check — ${new Date().toISOString()}\n`);
   console.log('Score | Days | Skill');
   console.log('------|------|-----');
@@ -383,13 +401,33 @@ async function runValidateCves(rawArgs = []) {
     process.exit(2);
   }
 
-  const cveIds = Object.keys(catalog).filter(k => /^CVE-\d{4}-\d{4,7}$/.test(k));
+  // --since <ISO|YYYY-MM-DD>: scope-limit validation to CVEs whose
+  // last_updated (or cisa_kev_date when missing) is on or after the given
+  // date. Cuts upstream calls for fleet operators running cron jobs.
+  let sinceDate = null;
+  for (let i = 0; i < rawArgs.length; i++) {
+    if (rawArgs[i] === '--since' && rawArgs[i + 1]) sinceDate = rawArgs[i + 1];
+    else if (rawArgs[i].startsWith('--since=')) sinceDate = rawArgs[i].slice('--since='.length);
+  }
+
+  let cveIds = Object.keys(catalog).filter(k => /^CVE-\d{4}-\d{4,7}$/.test(k));
+  if (sinceDate) {
+    const since = sinceDate.length === 10 ? `${sinceDate}T00:00:00Z` : sinceDate;
+    const before = cveIds.length;
+    cveIds = cveIds.filter(id => {
+      const e = catalog[id];
+      const stamp = e.last_updated || e.cisa_kev_date || e.first_seen;
+      if (!stamp) return false;
+      return stamp >= since;
+    });
+    console.log(`[validate-cves] --since ${sinceDate} filtered ${before} → ${cveIds.length} CVE(s).`);
+  }
 
   console.log(`\nCVE Validation — ${new Date().toISOString()}`);
   const modeStr = offline
     ? 'offline (local view only)'
     : (cacheDir ? `live with cache (${path.relative(path.join(__dirname, '..'), cacheDir)})` : 'live (NVD + CISA KEV)');
-  console.log(`${cveIds.length} CVEs in catalog. Mode: ${modeStr}`);
+  console.log(`${cveIds.length} CVEs in catalog. Mode: ${modeStr}${sinceDate ? ` · since=${sinceDate}` : ''}`);
   console.log(`Fail-on-drift: ${noFail ? 'disabled' : 'enabled'}\n`);
 
   // --- Header (fixed-width; works with the existing currency command's style)
@@ -436,7 +474,23 @@ async function runValidateCves(rawArgs = []) {
   // is set. Cache-resolved CVEs short-circuit the network fetch; missing
   // entries fall through to the live validator. Both paths produce the
   // same ValidationResult shape.
-  const { validateAllCves } = require('../sources/validators');
+  //
+  // Graceful fallback when sources/validators isn't shipped (matches the
+  // pattern validate-rfcs uses below). Pre-v0.10.3 this crashed with
+  // MODULE_NOT_FOUND in installed npm packages because sources/ wasn't
+  // in the files allowlist.
+  let validateAllCves;
+  try {
+    ({ validateAllCves } = require('../sources/validators'));
+  } catch (e) {
+    if (e.code === 'MODULE_NOT_FOUND') {
+      console.warn('[validate-cves] validator module unavailable (MODULE_NOT_FOUND); falling back to offline mode.');
+      console.log(`\n[validate-cves] offline mode (forced by missing validators) — ${cveIds.length} entries listed from local catalog.`);
+      process.exit(0);
+      return;
+    }
+    throw e;
+  }
   let report;
   if (cacheDir && fs.existsSync(cacheDir)) {
     report = await validateAllCvesPreferCache(catalog, cacheDir);
@@ -568,13 +622,29 @@ async function runValidateRfcs(rawArgs = []) {
     process.exit(2);
   }
 
-  const ids = Object.keys(refs).filter(k => !k.startsWith('_'));
+  // --since <ISO|YYYY-MM-DD>: scope-limit (parity with validate-cves).
+  let sinceDate = null;
+  for (let i = 0; i < rawArgs.length; i++) {
+    if (rawArgs[i] === '--since' && rawArgs[i + 1]) sinceDate = rawArgs[i + 1];
+    else if (rawArgs[i].startsWith('--since=')) sinceDate = rawArgs[i].slice('--since='.length);
+  }
+  let ids = Object.keys(refs).filter(k => !k.startsWith('_'));
+  if (sinceDate) {
+    const since = sinceDate.length === 10 ? `${sinceDate}T00:00:00Z` : sinceDate;
+    const before = ids.length;
+    ids = ids.filter(id => {
+      const e = refs[id];
+      const stamp = e.last_verified || e.published || e.last_updated;
+      return stamp && stamp >= since;
+    });
+    console.log(`[validate-rfcs] --since ${sinceDate} filtered ${before} → ${ids.length} entry(ies).`);
+  }
 
   console.log(`\nRFC Validation — ${new Date().toISOString()}`);
   const modeStr = offline
     ? 'offline (local view only)'
     : (cacheDir ? `live with cache (${path.relative(path.join(__dirname, '..'), cacheDir)})` : 'live (IETF Datatracker)');
-  console.log(`${ids.length} RFC / draft entries in catalog. Mode: ${modeStr}`);
+  console.log(`${ids.length} RFC / draft entries in catalog. Mode: ${modeStr}${sinceDate ? ` · since=${sinceDate}` : ''}`);
   console.log(`Fail-on-drift: ${noFail ? 'disabled' : 'enabled'}\n`);
 
   const header = 'ID                              | Status               | Errata | Last verified | Live status';
@@ -753,6 +823,26 @@ function runWatchlist(rawArgs = []) {
     }
   }
 
+  const jsonOut = rawArgs.includes('--json');
+  if (jsonOut) {
+    const out = {
+      generated_at: new Date().toISOString(),
+      skills_scanned: skills.length,
+      parse_errors: parseErrors,
+      mode: byskill ? 'by-skill' : 'by-item',
+    };
+    if (byskill) {
+      out.by_skill = Object.fromEntries([...skillToItems.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => [k, v]));
+    } else {
+      out.by_item = Object.fromEntries([...itemToSkills.entries()]
+        .sort(([a], [b]) => a.localeCompare(b)));
+    }
+    process.stdout.write(JSON.stringify(out) + '\n');
+    return;
+  }
+
   console.log(`\nForward-Watch Aggregator — ${new Date().toISOString()}`);
   console.log(`Skills scanned: ${skills.length}  parse errors: ${parseErrors}`);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/exceptd-skills",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "description": "AI security skills grounded in mid-2026 threat reality, not stale framework documentation. 38 skills, 10 catalogs, 34 jurisdictions, pre-computed indexes, Ed25519-signed.",
   "keywords": [
     "ai-security",
@@ -48,6 +48,7 @@
     "lib/",
     "orchestrator/",
     "scripts/",
+    "sources/validators/",
     "vendor/",
     "agents/",
     "data/",

package/sbom.cdx.json

@@ -1,10 +1,10 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.6",
-  "serialNumber": "urn:uuid:e91a4a28-720d-4270-94ce-eddb39e029c7",
+  "serialNumber": "urn:uuid:9c80f3b8-1fb8-46a8-b68f-e1b6a0ddedb7",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-12T13:34:59.113Z",
+    "timestamp": "2026-05-12T14:06:23.001Z",
     "tools": [
       {
         "name": "hand-written",
@@ -13,10 +13,10 @@
       }
     ],
     "component": {
-      "bom-ref": "pkg:npm/@blamejs/exceptd-skills@0.10.1",
+      "bom-ref": "pkg:npm/@blamejs/exceptd-skills@0.10.3",
       "type": "application",
       "name": "@blamejs/exceptd-skills",
-      "version": "0.10.1",
+      "version": "0.10.3",
       "description": "AI security skills grounded in mid-2026 threat reality, not stale framework documentation. 38 skills, 10 catalogs, 34 jurisdictions, pre-computed indexes, Ed25519-signed.",
       "licenses": [
         {
@@ -25,11 +25,11 @@
           }
         }
       ],
-      "purl": "pkg:npm/%40blamejs/exceptd-skills@0.10.1",
+      "purl": "pkg:npm/%40blamejs/exceptd-skills@0.10.3",
       "externalReferences": [
         {
           "type": "distribution",
-          "url": "https://www.npmjs.com/package/@blamejs/exceptd-skills/v/0.10.1"
+          "url": "https://www.npmjs.com/package/@blamejs/exceptd-skills/v/0.10.3"
         },
         {
           "type": "vcs",

package/sources/README.md

@@ -0,0 +1,170 @@
+# Sources
+
+The sources directory is the data quality gate for exceptd Security. Every claim in every skill must trace to a primary source. Bad data in produces bad analysis out — this directory makes source integrity a first-class concern.
+
+## The Problem: Data Corruption in Security Intelligence
+
+Security intelligence has several common failure modes:
+- **Stale data**: A CVE is marked as "no public PoC" when a PoC went public six months ago
+- **Misattribution**: A CVSS score copied from a secondary source that applied the wrong vector
+- **Fabricated details**: AI-summarized threat intel that introduced plausible-but-wrong specifics
+- **Framework version drift**: A control ID that changed in a framework revision but wasn't updated in skills
+- **Dead links**: Source URLs that return 404 — removing the ability to verify
+
+The sources system prevents these failures by:
+1. Maintaining a registry of authoritative primary sources per data type
+2. Providing validators that check data against primary sources
+3. Tracking source verification dates and flagging stale verifications
+4. Making multi-agent research verifiable and auditable
+
+---
+
+## Directory Structure
+
+```
+sources/
+├── README.md                  # This file
+├── index.json                 # Source registry — authoritative sources per data type
+├── SOURCES.md                 # Guide for adding and verifying sources
+├── validators/
+│   ├── cve-validator.js       # Cross-check CVE data against NVD API
+│   ├── kev-validator.js       # Verify CISA KEV status against official feed
+│   ├── atlas-validator.js     # Verify ATLAS TTP IDs against mitre.org
+│   └── framework-validator.js # Verify framework control IDs
+└── feeds/
+    ├── cisa-kev-snapshot.json # Snapshot of CISA KEV at last verification
+    ├── atlas-version.json     # Current ATLAS version metadata
+    └── nvd-recent.json        # Recent NVD entries (last 30 days)
+```
+
+---
+
+## Primary Sources by Data Type
+
+### CVE Data
+
+| Field | Authoritative Source | Update Frequency |
+|---|---|---|
+| CVSS score + vector | NVD (nvd.nist.gov/vuln/detail/CVE-XXXX) | On NVD analysis |
+| CISA KEV status | CISA KEV catalog (cisa.gov/known-exploited-vulnerabilities-catalog) | Real-time feed |
+| PoC availability | NVD references + researcher advisories | Monitor CVE references |
+| Active exploitation | CISA KEV, threat intelligence, incident reports | Monitor |
+| Affected versions | Vendor advisory (Red Hat, Ubuntu, etc.) | On vendor advisory |
+| Patch availability | Vendor advisory | On vendor advisory |
+| Live patch support | kpatch.com, ubuntu.com/security/livepatch, suse.com/products/live-patching | On vendor announcement |
+
+**Never use as primary source:** Wikipedia, news articles, blog posts, AI-generated summaries, secondary aggregators without NVD cross-reference.
+
+### ATLAS TTPs
+
+| Field | Authoritative Source |
+|---|---|
+| TTP ID | atlas.mitre.org (canonical IDs may change between versions) |
+| TTP name | atlas.mitre.org/techniques/ |
+| TTP version | atlas.mitre.org/resources/changelog |
+
+**ATLAS version pinning:** All skills reference a specific ATLAS version. When ATLAS updates, TTP IDs must be re-verified. The `atlas-validator.js` checks all skill `atlas_refs` against the current published ATLAS.
+
+### Framework Controls
+
+| Framework | Authoritative Source |
+|---|---|
+| NIST 800-53 Rev 5 | csrc.nist.gov/publications/detail/sp/800-53/rev-5/final |
+| ISO 27001:2022 | iso.org/standard/27001 (requires purchase for full text) |
+| SOC 2 | aicpa.org (TSC 2017) |
+| PCI DSS 4.0 | pcisecuritystandards.org/document_library |
+| NIS2 | eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32022L2555 |
+| DORA | eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32022R2554 |
+| EU AI Act | eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R1689 |
+| EU CRA | Official Journal of EU |
+| NCSC CAF | ncsc.gov.uk/collection/cyber-assessment-framework |
+| ASD ISM | cyber.gov.au/resources-business-and-government/essential-cyber-security/ism |
+| ASD Essential 8 | cyber.gov.au/resources-business-and-government/essential-cyber-security/essential-eight |
+| MAS TRM | mas.gov.sg/regulation/guidelines/technology-risk-management-guidelines |
+| CIS Controls v8 | cisecurity.org/controls/v8 |
+| CSA CCM v4 | cloudsecurityalliance.org/research/cloud-controls-matrix |
+
+### PQC Standards
+
+| Standard | Authoritative Source |
+|---|---|
+| FIPS 203 (ML-KEM) | csrc.nist.gov/pubs/fips/203/final |
+| FIPS 204 (ML-DSA) | csrc.nist.gov/pubs/fips/204/final |
+| FIPS 205 (SLH-DSA) | csrc.nist.gov/pubs/fips/205/final |
+| FIPS 206 (HQC, pending) | csrc.nist.gov/projects/post-quantum-cryptography |
+| OpenSSL 3.5 release notes | github.com/openssl/openssl/blob/master/CHANGES.md |
+| CNSA 2.0 | cnss.gov |
+
+---
+
+## Source Verification Requirement
+
+Every entry in `data/cve-catalog.json` must have a `source_verified` field:
+```json
+{
+  "source_verified": "2026-05-01",
+  "verification_sources": [
+    "https://nvd.nist.gov/vuln/detail/CVE-2026-31431",
+    "https://www.cisa.gov/known-exploited-vulnerabilities-catalog"
+  ]
+}
+```
+
+A `source_verified` date older than 90 days triggers a reverification requirement in the skill-update-loop.
+
+---
+
+## Multi-Agent Research Protocol
+
+When agents research new threat intelligence, they must:
+1. Identify primary sources (from the registry above)
+2. Record what was found at each source and when
+3. Cross-reference across at least 2 independent sources for critical claims
+4. Flag any claim that could only be verified from a single source
+5. Record the agent ID and timestamp in the `source_verified` audit trail
+
+See `agents/threat-researcher.md` for the research agent protocol.
+
+---
+
+## Bad Data Prevention
+
+These categories of sources are **rejected** for skill data:
+
+| Source Type | Why Rejected |
+|---|---|
+| AI-generated summaries without primary source citation | Plausible hallucination risk |
+| News articles | Often inaccurate on technical details, not updated when details change |
+| Blog posts | No editorial standard, often repost errors from other blogs |
+| Wikipedia | Community-edited, not authoritative for CVE details or framework text |
+| Secondary aggregators without NVD cross-reference | May lag or misquote NVD |
+| Social media / X posts | Not citable, not stable |
+| Forum posts | Not authoritative |
+
+The only exception: researcher/discoverer announcements about their own research (e.g., Hyunwoo Kim's Dirty Frag disclosure) may be used as a source alongside NVD, since the researcher is the primary source for their own findings.
+
+---
+
+## Validators
+
+Real validation against primary sources lives in `sources/validators/`. These are
+zero-dependency Node 24 modules (stdlib `fetch`, `AbortController`, `fs/promises`
+only). Every network call has a 10s timeout and degrades to an `unreachable`
+status rather than throwing — the validators are safe to run in airgapped CI.
+
+| Module | Purpose | Upstream |
+|---|---|---|
+| [`validators/cve-validator.js`](validators/cve-validator.js) | Cross-check one CVE's CVSS score, vector, and KEV status against NVD and the CISA KEV feed. Caches the KEV feed once per process. | NVD `services.nvd.nist.gov` + CISA KEV JSON |
+| [`validators/atlas-validator.js`](validators/atlas-validator.js) | Confirm the pinned MITRE ATLAS version (in `manifest.json` and `sources/index.json`) matches the latest upstream release. | GitHub releases for `mitre-atlas/atlas-data`, raw `ATLAS.yaml` fallback |
+| [`validators/index.js`](validators/index.js) | Barrel export plus `validateAllCves(catalog)` for catalog-wide aggregation with bounded concurrency. | — |
+
+The orchestrator wires the CVE validator into the CLI:
+
+```
+node orchestrator/index.js validate-cves            # live cross-check, non-zero exit on drift
+node orchestrator/index.js validate-cves --offline  # local view only, no network
+node orchestrator/index.js validate-cves --no-fail  # report drift but always exit 0
+```
+
+Feed snapshots are written under `sources/feeds/`; see `sources/feeds/README.md`
+for the cache contract and freshness thresholds.

package/sources/validators/atlas-validator.js

@@ -0,0 +1,158 @@
+'use strict';
+
+/**
+ * atlas-validator.js — Confirm pinned MITRE ATLAS version against upstream.
+ *
+ * Zero npm dependencies. Node 24 stdlib only.
+ *
+ * MITRE ATLAS does not (as of v5.x) publish a stable machine-readable changelog JSON.
+ * The canonical source-of-truth for releases is the public GitHub repo:
+ *   https://raw.githubusercontent.com/mitre-atlas/atlas-data/main/dist/ATLAS.yaml
+ * which carries an `id: ATLAS` / `version: x.y.z` header. The GitHub releases API
+ * also lists tagged versions:
+ *   https://api.github.com/repos/mitre-atlas/atlas-data/releases/latest
+ *
+ * We prefer the releases API (lightweight JSON, no YAML parsing), fall back to the
+ * raw YAML version line, and finally report unreachable if both fail. Both are
+ * read-only public endpoints; no auth is required.
+ *
+ * Exported:
+ *   validateAtlasVersion(opts?) -> Promise<{
+ *     pinned: string|null,
+ *     pinned_sources: { manifest: string|null, index: string|null },
+ *     latest: string|null,
+ *     drift: boolean,
+ *     status: 'match'|'drift'|'unreachable'|'unknown',
+ *     fetched_from: string|null,
+ *     error: string|null
+ *   }>
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const REQUEST_TIMEOUT_MS = 10_000;
+const USER_AGENT = 'exceptd-security/atlas-validator (+https://exceptd.com)';
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const MANIFEST_PATH = path.join(REPO_ROOT, 'manifest.json');
+const SOURCES_INDEX_PATH = path.join(REPO_ROOT, 'sources', 'index.json');
+
+const GH_RELEASE_URL = 'https://api.github.com/repos/mitre-atlas/atlas-data/releases/latest';
+const RAW_ATLAS_YAML = 'https://raw.githubusercontent.com/mitre-atlas/atlas-data/main/dist/ATLAS.yaml';
+
+async function timedFetch(url, accept = 'application/json') {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      signal: controller.signal,
+      headers: { 'User-Agent': USER_AGENT, Accept: accept },
+    });
+    if (!res.ok) return { ok: false, error: `HTTP ${res.status}` };
+    const body = accept.includes('json') ? await res.json() : await res.text();
+    return { ok: true, body };
+  } catch (err) {
+    const code = err.name === 'AbortError' ? 'timeout' : (err.code || 'network_error');
+    return { ok: false, error: `${code}: ${err.message}` };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function normalizeVersion(v) {
+  if (!v || typeof v !== 'string') return null;
+  // Strip leading "v" / "ATLAS-v" prefixes; trim.
+  return v.trim().replace(/^ATLAS[-_ ]?/i, '').replace(/^v/i, '');
+}
+
+async function readPinnedVersions() {
+  const out = { manifest: null, index: null };
+  try {
+    const manifest = JSON.parse(await fs.readFile(MANIFEST_PATH, 'utf8'));
+    out.manifest = normalizeVersion(
+      manifest?._meta?.atlas_version || manifest?.atlas_version || null
+    );
+  } catch { /* leave null */ }
+  try {
+    const idx = JSON.parse(await fs.readFile(SOURCES_INDEX_PATH, 'utf8'));
+    out.index = normalizeVersion(idx?.sources?.atlas?.current_version || null);
+  } catch { /* leave null */ }
+  return out;
+}
+
+async function fetchLatestFromGithubReleases() {
+  const res = await timedFetch(GH_RELEASE_URL);
+  if (!res.ok) return { ok: false, error: res.error };
+  const tag = res.body?.tag_name || res.body?.name || null;
+  const version = normalizeVersion(tag);
+  if (!version) return { ok: false, error: 'no tag_name in response' };
+  return { ok: true, version, source: 'github-releases' };
+}
+
+async function fetchLatestFromRawYaml() {
+  const res = await timedFetch(RAW_ATLAS_YAML, 'text/yaml');
+  if (!res.ok) return { ok: false, error: res.error };
+  // Naive YAML scrape: look for a top-level `version:` line within the first 200 lines.
+  const text = String(res.body).split(/\r?\n/).slice(0, 200).join('\n');
+  const match = text.match(/^version:\s*['"]?([0-9]+(?:\.[0-9]+){1,2})['"]?\s*$/m);
+  if (!match) return { ok: false, error: 'version line not found in ATLAS.yaml' };
+  return { ok: true, version: normalizeVersion(match[1]), source: 'raw-yaml' };
+}
+
+async function validateAtlasVersion(_opts = {}) {
+  const pinned_sources = await readPinnedVersions();
+  // Canonical pinned value: prefer manifest._meta or top-level, then sources/index.json.
+  const pinned = pinned_sources.manifest || pinned_sources.index || null;
+
+  // Cross-check that the two pinned locations agree.
+  const pinnedDisagree =
+    pinned_sources.manifest &&
+    pinned_sources.index &&
+    pinned_sources.manifest !== pinned_sources.index;
+
+  // Try GitHub releases first, fall back to raw YAML.
+  let upstream = await fetchLatestFromGithubReleases();
+  if (!upstream.ok) {
+    const fallback = await fetchLatestFromRawYaml();
+    if (fallback.ok) upstream = fallback;
+  }
+
+  if (!upstream.ok) {
+    return {
+      pinned,
+      pinned_sources,
+      latest: null,
+      drift: pinnedDisagree === true, // internal drift is still reportable offline
+      status: 'unreachable',
+      fetched_from: null,
+      error: upstream.error,
+    };
+  }
+
+  const latest = upstream.version;
+  if (!pinned) {
+    return {
+      pinned: null,
+      pinned_sources,
+      latest,
+      drift: true,
+      status: 'unknown',
+      fetched_from: upstream.source,
+      error: 'no pinned ATLAS version found in manifest.json or sources/index.json',
+    };
+  }
+
+  const drift = pinned !== latest || pinnedDisagree === true;
+  return {
+    pinned,
+    pinned_sources,
+    latest,
+    drift,
+    status: drift ? 'drift' : 'match',
+    fetched_from: upstream.source,
+    error: null,
+  };
+}
+
+module.exports = { validateAtlasVersion };