@vegastack/skills 0.1.0

package/skill/vegastack-arch-guardian/scripts/refresh-evidence.mjs

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+import { randomUUID } from 'node:crypto'
+import { lookup } from 'node:dns/promises'
+import { lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { isIP } from 'node:net'
+import { dirname, join, parse, relative, resolve, sep } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { pathExists, readJsonYaml, sha256 } from './lib.mjs'
+
+const skillRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const defaultRegistry = join(skillRoot, 'refresh', 'sources.json')
+const maximumBytes = 5 * 1024 * 1024
+// Every host referenced by refresh/sources.json must appear here; loadRegistry enforces the
+// consistency so the allowlist cannot silently drift from the registry.
+const approvedHosts = new Set(['ai-sdk.dev', 'ai.google.dev', 'api.flutter.dev', 'aws.amazon.com', 'better-auth.com', 'bun.sh', 'developer.apple.com', 'developers.cloudflare.com', 'developers.openai.com', 'docs.aws.amazon.com', 'docs.flutter.dev', 'firebase.google.com', 'git.postgresql.org', 'github.com', 'modal.com', 'modelcontextprotocol.io', 'nextjs.org', 'openbao.org', 'openid.github.io', 'opennext.js.org', 'opentelemetry.io', 'platform.claude.com', 'pub.dev', 'pypi.org', 'raw.githubusercontent.com', 'registry.npmjs.org', 'riverpod.dev', 'turborepo.dev', 'workflow-sdk.dev', 'www.cloudflare.com', 'www.npmjs.com', 'www.postgresql.org'])
+
+function flagValue(argv, flag) {
+  const value = argv.shift()
+  if (value === undefined || value.startsWith('-')) throw new Error(`${flag} requires a value`)
+  return value
+}
+
+function args(argv) {
+  const result = { registry: defaultRegistry, cache: '.vegastack/evidence-cache.json', report: '.vegastack/evidence-drift.json', topics: [], offline: false, acceptBaselines: false, now: new Date().toISOString() }
+  while (argv.length) {
+    const flag = argv.shift()
+    if (flag === '--registry') result.registry = resolve(flagValue(argv, flag))
+    else if (flag === '--cache') result.cache = resolve(flagValue(argv, flag))
+    else if (flag === '--report') result.report = resolve(flagValue(argv, flag))
+    else if (flag === '--topics') result.topics = flagValue(argv, flag).split(',').filter(Boolean)
+    else if (flag === '--offline') result.offline = true
+    else if (flag === '--accept-baselines') result.acceptBaselines = true
+    else if (flag === '--verify-baselines') { /* explicit alias for the default online verification run */ }
+    else if (flag === '--now') result.now = flagValue(argv, flag)
+    else throw new Error(`Unknown option: ${flag}`)
+  }
+  return result
+}
+
+function privateAddress(address) {
+  if (address === '::1' || address === '::' || address.startsWith('fc') || address.startsWith('fd') || address.startsWith('fe80:')) return true
+  if (!isIP(address)) return true
+  // IPv4-mapped IPv6 must be evaluated as its IPv4 payload, not passed as "public IPv6" —
+  // in both dotted (::ffff:10.0.0.1) and hex-group (::ffff:a00:1) notations.
+  const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address)
+  if (mapped) return privateAddress(mapped[1])
+  const hexMapped = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i.exec(address)
+  if (hexMapped) {
+    const high = Number.parseInt(hexMapped[1], 16)
+    const low = Number.parseInt(hexMapped[2], 16)
+    return privateAddress(`${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`)
+  }
+  if (address.includes(':')) return false
+  const [a, b] = address.split('.').map(Number)
+  if (a === 0 || a === 10 || a === 127 || a >= 224) return true
+  if (a === 169 && b === 254) return true
+  if (a === 172 && b >= 16 && b <= 31) return true
+  if (a === 192 && (b === 168 || b === 0)) return true
+  if (a === 100 && b >= 64 && b <= 127) return true // CGNAT 100.64/10
+  if (a === 198 && (b === 18 || b === 19 || b === 51)) return true // benchmark + TEST-NET-2
+  if (a === 203 && b === 0) return true // TEST-NET-3
+  return false
+}
+
+// NOTE: validation resolves DNS immediately before each fetch (including every redirect hop), but
+// Node fetch re-resolves independently, so a hostile authoritative DNS server could still rebind
+// between the check and the request. The hard host allowlist above is the primary control; this
+// check is defense in depth against allowlisted-host compromise, not a substitute for it.
+async function validateNetworkTarget(input, allowHttpLocalhost = false) {
+  const url = new URL(input)
+  const loopbackName = ['localhost', '127.0.0.1', '::1', '[::1]'].includes(url.hostname)
+  if (url.protocol !== 'https:' && !(allowHttpLocalhost && url.protocol === 'http:' && loopbackName)) throw new Error(`Only HTTPS evidence URLs are allowed: ${url}`)
+  if (!approvedHosts.has(url.hostname) && !(allowHttpLocalhost && loopbackName)) throw new Error(`Unapproved evidence host: ${url.hostname}`)
+  const addresses = isIP(url.hostname) ? [{ address: url.hostname }] : await lookup(url.hostname, { all: true, verbatim: true })
+  if ((!allowHttpLocalhost || !loopbackName) && addresses.some(entry => privateAddress(entry.address))) throw new Error(`Private/reserved evidence target refused: ${url.hostname}`)
+  return url
+}
+
+async function readBounded(response) {
+  const declared = Number(response.headers.get('content-length') ?? 0)
+  if (declared > maximumBytes) throw new Error(`Evidence response exceeds ${maximumBytes} bytes`)
+  if (!response.body) return new Uint8Array()
+  const reader = response.body.getReader()
+  const chunks = []
+  let total = 0
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    total += value.byteLength
+    if (total > maximumBytes) { await reader.cancel(); throw new Error(`Evidence response exceeds ${maximumBytes} bytes`) }
+    chunks.push(value)
+  }
+  const output = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) { output.set(chunk, offset); offset += chunk.byteLength }
+  return output
+}
+
+async function safeFetch(input, init = {}, allowHttpLocalhost = false) {
+  let url = await validateNetworkTarget(input, allowHttpLocalhost)
+  for (let redirects = 0; redirects <= 5; redirects += 1) {
+    const response = await fetch(url, { ...init, redirect: 'manual', signal: AbortSignal.timeout(20_000) })
+    if (![301, 302, 303, 307, 308].includes(response.status)) return response
+    const location = response.headers.get('location')
+    if (!location || redirects === 5) throw new Error('Invalid or excessive evidence redirect')
+    url = await validateNetworkTarget(new URL(location, url).href, allowHttpLocalhost)
+  }
+  throw new Error('Evidence redirect limit exceeded')
+}
+
+async function assertSafeWriteTarget(input) {
+  const target = resolve(input)
+  const root = parse(target).root
+  const segments = relative(root, target).split(sep).filter(Boolean)
+  let current = root
+  for (const part of segments) {
+    current = join(current, part)
+    try {
+      const entry = await lstat(current)
+      if (entry.isSymbolicLink()) throw new Error(`Refusing write through symlink: ${current}`)
+    } catch (error) {
+      if (error?.code === 'ENOENT') break
+      throw error
+    }
+  }
+  await mkdir(dirname(target), { recursive: true })
+  current = root
+  for (const part of segments) {
+    current = join(current, part)
+    try {
+      if ((await lstat(current)).isSymbolicLink()) throw new Error(`Refusing write through symlink: ${current}`)
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error
+    }
+  }
+  return target
+}
+
+async function atomicJson(path, value) {
+  const target = await assertSafeWriteTarget(path)
+  const temporary = join(dirname(target), `.${randomUUID()}.tmp`)
+  try {
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx' })
+    await rename(temporary, target)
+  } finally {
+    await rm(temporary, { force: true }).catch(() => {})
+  }
+}
+
+const ownerFor = source => source.owner ?? 'maintainers'
+
+function item(source, extra = {}) {
+  return { id: source.id, critical: Boolean(source.critical), owner: ownerFor(source), affected: source.affected, ...extra }
+}
+
+function evidenceChecksum(source, policy, bytes) {
+  const scope = source.checksumScope ?? policy?.defaultChecksumScope
+  if (scope === 'http-body') return sha256(bytes)
+  if (scope === 'html-text-v1') {
+    const document = new TextDecoder().decode(bytes)
+    const claimSurface = document.match(/<main\b[^>]*>([\s\S]*?)<\/main>/i)?.[1] ?? document
+    const normalized = claimSurface
+      .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '')
+      .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, '')
+      .replace(/<[^>]+>/g, ' ')
+      .replace(/&(?:nbsp|#x27|quot|amp|lt|gt);/g, ' ')
+      .replace(/\s+/g, ' ')
+      .trim()
+    return sha256(normalized)
+  }
+  throw new Error(`Unsupported checksum scope for ${source.id}: ${scope}`)
+}
+
+async function detectVersion(source, allowHttpLocalhost) {
+  const detection = source.versionDetection ?? {}
+  if (detection.type === 'npm' || detection.type === 'npm-suite') {
+    const packages = detection.type === 'npm-suite' ? detection.packages : [detection.package]
+    const tag = detection.tag ?? 'latest'
+    const versions = []
+    for (const packageName of packages) {
+      const response = await safeFetch(`https://registry.npmjs.org/${encodeURIComponent(packageName)}/${encodeURIComponent(tag)}`, {}, allowHttpLocalhost)
+      if (!response.ok) throw new Error(`npm version detection HTTP ${response.status} for ${packageName}`)
+      const metadata = JSON.parse(new TextDecoder().decode(await readBounded(response)))
+      versions.push(metadata.version ?? null)
+    }
+    const unique = [...new Set(versions)]
+    return unique.length === 1 ? unique[0] : versions.map((version, index) => `${packages[index]}@${version}`).join(',')
+  }
+  if (detection.type === 'pypi') {
+    const response = await safeFetch(`https://pypi.org/pypi/${encodeURIComponent(detection.package)}/json`, {}, allowHttpLocalhost)
+    if (!response.ok) throw new Error(`PyPI version detection HTTP ${response.status}`)
+    return JSON.parse(new TextDecoder().decode(await readBounded(response))).info?.version ?? null
+  }
+  return null
+}
+
+function validAgeDays(prior, now) {
+  const retrieved = prior?.retrievedAt ? new Date(prior.retrievedAt) : null
+  if (!retrieved || Number.isNaN(retrieved.getTime()) || retrieved.getTime() > now.getTime()) return Infinity
+  return (now.getTime() - retrieved.getTime()) / 86_400_000
+}
+
+async function verifyLocalIntegrity(source) {
+  if (!source.path) return null
+  if (source.treeChecksumAlgorithm === 'git-sha1-tree' || source.checksumAlgorithm === 'git-sha1-tree') {
+    const expected = source.treeChecksum ?? source.checksum
+    const result = spawnSync('git', ['-C', source.path, 'rev-parse', 'HEAD^{tree}'], { encoding: 'utf8' })
+    if (result.status !== 0) throw new Error(result.stderr.trim() || 'git tree checksum failed')
+    return { expected, actual: result.stdout.trim(), algorithm: 'git-sha1-tree' }
+  }
+  if (source.refreshable === false) return { expected: source.checksum, actual: sha256(await readFile(source.path)), algorithm: 'sha256' }
+  return null
+}
+
+function validateRegistry(registry, options) {
+  if (registry.schemaVersion !== 1 || !Array.isArray(registry.sources)) throw new Error('Invalid evidence registry schema')
+  const sourceIds = new Set()
+  for (const source of registry.sources) {
+    if (!source.id || sourceIds.has(source.id) || !Array.isArray(source.topics) || !Number.isFinite(source.thresholdDays) || source.thresholdDays < 1) throw new Error(`Invalid evidence registry entry: ${source.id ?? 'unknown'}`)
+    sourceIds.add(source.id)
+    if (source.refreshable !== false) {
+      const scope = source.checksumScope ?? registry.policy?.defaultChecksumScope
+      if (!['http-body', 'html-text-v1'].includes(scope)) throw new Error(`Refreshable source ${source.id} has unsupported checksum scope ${scope}`)
+      // --accept-baselines seeds missing baselines for newly added sources; every other mode requires them.
+      if (!/^[a-f0-9]{64}$/.test(source.checksum ?? '') && !options.acceptBaselines) throw new Error(`Refreshable source ${source.id} requires an explicit supported SHA-256 baseline`)
+      for (const url of Object.values(source.urls ?? {})) {
+        const hostname = new URL(url).hostname
+        const loopback = ['localhost', '127.0.0.1', '::1', '[::1]'].includes(hostname)
+        if (!approvedHosts.has(hostname) && !(options.allowHttpLocalhost && loopback)) throw new Error(`Registry source ${source.id} references unapproved host ${hostname}; update approvedHosts in refresh-evidence.mjs deliberately`)
+      }
+    }
+  }
+}
+
+export async function refreshEvidence(options) {
+  const registry = await readJsonYaml(options.registry)
+  validateRegistry(registry, options)
+  const cache = await pathExists(options.cache) ? JSON.parse(await readFile(options.cache, 'utf8')) : { schemaVersion: 1, sources: {} }
+  const now = new Date(options.now)
+  if (Number.isNaN(now.getTime())) throw new Error(`Invalid --now timestamp: ${options.now}`)
+  const selected = registry.sources.filter(source => !options.topics.length || source.topics.some(topic => options.topics.includes(topic)))
+  const report = { schemaVersion: 1, generatedAt: now.toISOString(), offline: options.offline, acceptBaselines: options.acceptBaselines, selected: selected.map(source => source.id), drift: [], versionDrift: [], stale: [], unavailable: [], unaffected: [], manualVersionReview: [], acceptedBaselines: [] }
+  const baselineUpdates = new Map()
+  for (const source of selected) {
+    const prior = cache.sources[source.id]
+    const ageDays = validAgeDays(prior, now)
+    try {
+      const local = await verifyLocalIntegrity(source)
+      if (local && local.actual !== local.expected) {
+        report.drift.push(item(source, { from: local.expected, to: local.actual, integrityFailure: true, scope: local.algorithm }))
+        continue
+      }
+      if (source.refreshable === false) {
+        report.unaffected.push(source.id)
+        cache.sources[source.id] = { retrievedAt: now.toISOString(), checksum: local.actual, local: true, path: source.path }
+        continue
+      }
+      if (options.offline) {
+        if (!prior || !Number.isFinite(ageDays) || ageDays > source.thresholdDays) report.stale.push(item(source, { ageDays: Number.isFinite(ageDays) ? Math.floor(ageDays) : null }))
+        else report.unaffected.push(source.id)
+        continue
+      }
+      const detectedVersion = await detectVersion(source, options.allowHttpLocalhost)
+      if (detectedVersion && detectedVersion !== source.currentVersion) {
+        // Under --accept-baselines a verified version change is accepted, not re-reported as drift —
+        // the same single-code-path rule the checksum branch follows.
+        if (options.acceptBaselines) baselineUpdates.set(source.id, { ...(baselineUpdates.get(source.id) ?? {}), currentVersion: detectedVersion, versionCheckedAt: now.toISOString() })
+        else report.versionDrift.push(item(source, { from: source.currentVersion, to: detectedVersion, detection: source.versionDetection.type }))
+      } else if (!detectedVersion && !['parent', 'git-commit'].includes(source.versionDetection?.type)) {
+        const reviewedAgeDays = validAgeDays({ retrievedAt: source.retrievedAt }, now)
+        report.manualVersionReview.push({ id: source.id, critical: Boolean(source.critical), owner: ownerFor(source), mechanism: source.versionDetection?.type ?? 'unspecified', due: !Number.isFinite(reviewedAgeDays) || reviewedAgeDays > source.thresholdDays, ageDays: Number.isFinite(reviewedAgeDays) ? Math.floor(reviewedAgeDays) : null })
+      }
+      const headers = {}
+      if (prior?.etag) headers['If-None-Match'] = prior.etag
+      if (prior?.lastModified) headers['If-Modified-Since'] = prior.lastModified
+      const response = await safeFetch(source.urls.primary, { headers }, options.allowHttpLocalhost)
+      if (response.status === 304 && prior) {
+        if (prior.checksum !== source.checksum) {
+          if (!options.acceptBaselines) {
+            report.drift.push(item(source, { from: source.checksum, to: prior.checksum, baseline: 'registry-vs-304-cache' }))
+            continue
+          }
+          baselineUpdates.set(source.id, { ...(baselineUpdates.get(source.id) ?? {}), checksum: prior.checksum, retrievedAt: now.toISOString() })
+        }
+        prior.retrievedAt = now.toISOString()
+        report.unaffected.push(source.id)
+        continue
+      }
+      if (!response.ok) throw new Error(`HTTP ${response.status}`)
+      const checksum = evidenceChecksum(source, registry.policy, await readBounded(response))
+      const comparison = prior?.checksum ?? source.checksum
+      if (comparison && comparison !== checksum && !options.acceptBaselines) report.drift.push(item(source, { from: comparison, to: checksum, baseline: prior?.checksum ? 'cache' : 'registry' }))
+      else report.unaffected.push(source.id)
+      if (options.acceptBaselines && source.checksum !== checksum) {
+        baselineUpdates.set(source.id, { ...(baselineUpdates.get(source.id) ?? {}), checksum, retrievedAt: now.toISOString() })
+      }
+      cache.sources[source.id] = { retrievedAt: now.toISOString(), checksum, etag: response.headers.get('etag'), lastModified: response.headers.get('last-modified'), url: response.url, detectedVersion }
+    } catch (error) {
+      report.unavailable.push(item(source, { error: error.message }))
+    }
+  }
+  // Accepted baselines are written back to the registry in the same run that produced the report,
+  // so the registry snapshot, cache, and drift report can never disagree (single code path).
+  if (options.acceptBaselines && baselineUpdates.size) {
+    for (const source of registry.sources) {
+      const update = baselineUpdates.get(source.id)
+      if (!update) continue
+      Object.assign(source, update)
+      report.acceptedBaselines.push({ id: source.id, ...update })
+    }
+    await atomicJson(options.registry, registry)
+  }
+  await atomicJson(options.cache, cache)
+  await atomicJson(options.report, report)
+  const failClosed = [...report.stale, ...report.unavailable, ...report.drift, ...report.versionDrift, ...report.manualVersionReview.filter(entry => entry.due)].some(entry => entry.critical || entry.integrityFailure)
+  return { report, failClosed }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  const options = args(process.argv.slice(2))
+  const { report, failClosed } = await refreshEvidence(options)
+  console.log(`refresh-evidence: selected=${report.selected.length} drift=${report.drift.length} version-drift=${report.versionDrift.length} stale=${report.stale.length} unavailable=${report.unavailable.length}${report.acceptedBaselines.length ? ` accepted=${report.acceptedBaselines.length}` : ''}`)
+  if (failClosed) process.exitCode = 1
+}

package/skill/vegastack-arch-guardian/scripts/schema-validate.mjs

@@ -0,0 +1,63 @@
+function pointer(root, reference) {
+  if (!reference.startsWith('#/')) throw new Error(`Only local JSON Schema references are supported: ${reference}`)
+  return reference.slice(2).split('/').reduce((value, key) => value?.[key.replaceAll('~1', '/').replaceAll('~0', '~')], root)
+}
+
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right)
+const typeOf = value => Array.isArray(value) ? 'array' : value === null ? 'null' : typeof value
+const joinPath = (base, key) => `${base}/${String(key).replaceAll('~', '~0').replaceAll('/', '~1')}`
+const validDate = value => {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false
+  const [year, month, day] = value.split('-').map(Number)
+  const parsed = new Date(Date.UTC(year, month - 1, day))
+  return parsed.getUTCFullYear() === year && parsed.getUTCMonth() === month - 1 && parsed.getUTCDate() === day
+}
+
+export function validateJsonSchema(schema, value) {
+  const errors = []
+  function validate(node, data, path = '$', quiet = false) {
+    const local = []
+    const add = message => local.push(`${path}: ${message}`)
+    if (node.$ref) return validate(pointer(schema, node.$ref), data, path, quiet)
+    if (node.const !== undefined && !same(data, node.const)) add(`must equal ${JSON.stringify(node.const)}`)
+    if (node.enum && !node.enum.some(item => same(item, data))) add(`must be one of ${node.enum.map(item => JSON.stringify(item)).join(', ')}`)
+    if (node.type) {
+      const allowed = Array.isArray(node.type) ? node.type : [node.type]
+      if (!allowed.includes(typeOf(data)) || (typeOf(data) === 'number' && !Number.isFinite(data))) add(`must be ${allowed.join(' or ')}`)
+    }
+    if (typeof data === 'string') {
+      if (node.minLength !== undefined && data.length < node.minLength) add(`must have length >= ${node.minLength}`)
+      if (node.pattern && !new RegExp(node.pattern).test(data)) add(`must match ${node.pattern}`)
+      if (node.format === 'date' && !validDate(data)) add('must be a real ISO calendar date (YYYY-MM-DD)')
+    }
+    if (typeof data === 'number' && node.minimum !== undefined && data < node.minimum) add(`must be >= ${node.minimum}`)
+    if (Array.isArray(data)) {
+      if (node.minItems !== undefined && data.length < node.minItems) add(`must contain at least ${node.minItems} item(s)`)
+      if (node.uniqueItems && new Set(data.map(item => JSON.stringify(item))).size !== data.length) add('must contain unique items')
+      if (node.items) data.forEach((item, index) => local.push(...validate(node.items, item, joinPath(path, index), true)))
+    }
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+      const keys = Object.keys(data)
+      if (node.minProperties !== undefined && keys.length < node.minProperties) add(`must contain at least ${node.minProperties} properties`)
+      for (const required of node.required ?? []) if (!(required in data)) local.push(`${joinPath(path, required)}: is required`)
+      for (const [key, child] of Object.entries(node.properties ?? {})) if (key in data) local.push(...validate(child, data[key], joinPath(path, key), true))
+      if (node.propertyNames) for (const key of keys) local.push(...validate(node.propertyNames, key, `${path} property ${JSON.stringify(key)}`, true))
+      const known = new Set(Object.keys(node.properties ?? {}))
+      for (const key of keys.filter(key => !known.has(key))) {
+        if (node.additionalProperties === false) local.push(`${joinPath(path, key)}: additional property is not allowed`)
+        else if (node.additionalProperties && typeof node.additionalProperties === 'object') local.push(...validate(node.additionalProperties, data[key], joinPath(path, key), true))
+      }
+    }
+    for (const child of node.allOf ?? []) local.push(...validate(child, data, path, true))
+    if (node.oneOf) {
+      const matches = node.oneOf.map(child => validate(child, data, path, true)).filter(result => result.length === 0).length
+      if (matches !== 1) add(`must match exactly one schema branch (matched ${matches})`)
+    }
+    if (node.not && validate(node.not, data, path, true).length === 0) add('must not match forbidden schema')
+    if (node.if && validate(node.if, data, path, true).length === 0 && node.then) local.push(...validate(node.then, data, path, true))
+    if (!quiet) errors.push(...local)
+    return local
+  }
+  validate(schema, value)
+  return errors
+}

package/skill/vegastack-arch-guardian/scripts/validate-profile.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+import { lstat, readFile, realpath } from 'node:fs/promises'
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { listFiles, pathExists, readJsonYaml, resolveProfile } from './lib.mjs'
+import { validateJsonSchema } from './schema-validate.mjs'
+
+const skillRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const architectureRoot = join(skillRoot, 'references', 'architecture')
+const schemaPath = join(skillRoot, 'assets', 'architecture-profile.schema.json')
+const compatibilityPath = join(skillRoot, 'references', 'foundation-compatibility.json')
+
+export async function canonicalRuleIds() {
+  const ids = new Set()
+  const duplicates = new Set()
+  for (const path of await listFiles(architectureRoot, file => file.endsWith('.md'))) {
+    const body = await readFile(path, 'utf8')
+    for (const match of body.matchAll(/\*\*([A-Z]+-[0-9]{3}) —/g)) {
+      if (ids.has(match[1])) duplicates.add(match[1])
+      ids.add(match[1])
+    }
+  }
+  if (duplicates.size) throw new Error(`Duplicate canonical rule IDs: ${[...duplicates].join(', ')}`)
+  return ids
+}
+
+const enabled = (profile, name) => profile.capabilities?.[name]?.status === 'enabled'
+const control = (profile, capability, name) => profile.capabilities?.[capability]?.controls?.[name]
+const exactVersion = /^\d+\.\d+(?:\.\d+)?(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
+const diag = (rule, controlId, path, message, exceptionEligible = true) => ({ rule, control: controlId, path, message, exceptionEligible })
+
+async function containedFile(projectRoot, targetPath) {
+  if (isAbsolute(targetPath) || targetPath.split(/[\\/]/).includes('..')) throw new Error('path must be repository-relative without ..')
+  const target = resolve(projectRoot, targetPath)
+  let current = resolve(projectRoot)
+  for (const part of relative(current, target).split(sep).filter(Boolean)) {
+    current = resolve(current, part)
+    if ((await lstat(current)).isSymbolicLink()) throw new Error('symlink component')
+  }
+  const resolvedRoot = await realpath(projectRoot)
+  const resolvedTarget = await realpath(target)
+  if (relative(resolvedRoot, resolvedTarget).startsWith('..') || !(await lstat(resolvedTarget)).isFile()) throw new Error('outside project or not a file')
+  return resolvedTarget
+}
+
+function metadata(body, key) {
+  return body.match(new RegExp(`^- ${key}:\\s*(.+)$`, 'mi'))?.[1]?.trim()
+}
+
+async function validateExceptions(profile, projectRoot, now, knownRules) {
+  const states = []
+  const seen = new Set()
+  for (const exception of profile.exceptions ?? []) {
+    const reasons = []
+    if (seen.has(exception.id)) reasons.push(`duplicate exception id ${exception.id}`)
+    seen.add(exception.id)
+    if (!knownRules.has(exception.ruleId)) reasons.push(`unknown canonical rule ${exception.ruleId}`)
+    for (const path of exception.paths ?? []) if (path.includes('*')) reasons.push('wildcard paths are forbidden')
+    if (exception.review?.date) {
+      const [year, month, day] = String(exception.review.date).split('-').map(Number)
+      const parsed = new Date(Date.UTC(year, month - 1, day))
+      const validCalendarDate = /^\d{4}-\d{2}-\d{2}$/.test(exception.review.date) && parsed.getUTCFullYear() === year && parsed.getUTCMonth() === month - 1 && parsed.getUTCDate() === day
+      const expiry = validCalendarDate ? Date.parse(`${exception.review.date}T23:59:59Z`) : Number.NaN
+      if (!Number.isFinite(expiry)) reasons.push('review.date is not a real ISO calendar date')
+      else if (expiry < now.getTime()) reasons.push(`exception expired on ${exception.review.date}`)
+    }
+    try {
+      const adrPath = await containedFile(projectRoot, String(exception.adr ?? ''))
+      const body = await readFile(adrPath, 'utf8')
+      const requiredHeadings = ['## Decision and rationale', '## Risks and accepted deviation', '## Compensating controls', '## Verification', '## Rollback or migration', '## Review trigger']
+      for (const heading of requiredHeadings) if (!body.includes(heading)) reasons.push(`ADR missing ${heading}`)
+      const checks = {
+        'Status': 'accepted',
+        'Project-Owner': exception.projectOwner,
+        'Rule-ID': exception.ruleId,
+        'Exception-ID': exception.id,
+        'Foundation-Deviation-Acknowledged': 'true'
+      }
+      for (const [key, expected] of Object.entries(checks)) if (metadata(body, key) !== String(expected)) reasons.push(`ADR ${key} must equal ${expected}`)
+      const adrControls = new Set((metadata(body, 'Control-IDs') ?? '').split(',').map(item => item.trim()).filter(Boolean))
+      const adrPaths = new Set((metadata(body, 'Scope-Paths') ?? '').split(',').map(item => item.trim()).filter(Boolean))
+      if (exception.controls) {
+        if (exception.controls.some(item => !adrControls.has(item)) || adrControls.size !== exception.controls.length) reasons.push('ADR Control-IDs do not exactly match profile')
+      } else if (metadata(body, 'Control-IDs') !== 'all') {
+        // A rule-level exception (no controls list) covers every control under its rule; the ADR
+        // must acknowledge that breadth explicitly.
+        reasons.push('ADR Control-IDs must equal all for a rule-level exception without a controls list')
+      }
+      if ((exception.paths ?? []).some(item => !adrPaths.has(item)) || adrPaths.size !== (exception.paths ?? []).length) reasons.push('ADR Scope-Paths do not exactly match profile')
+      if (exception.review?.date && metadata(body, 'Review-Date') !== exception.review.date) reasons.push('ADR Review-Date does not match profile')
+      if (exception.review?.event && metadata(body, 'Review-Event') !== exception.review.event) reasons.push('ADR Review-Event does not match profile')
+    } catch (error) { reasons.push(`ADR invalid or not found: ${error.message}`) }
+    if (exception.status !== 'active') reasons.push(`exception status is ${exception.status}`)
+    states.push({ exception, valid: reasons.length === 0, reasons })
+  }
+  return states
+}
+
+function requiredFamilyVersions(profile, compatibility) {
+  const baseline = compatibility.baselines?.[profile.foundation?.baseline]
+  if (!baseline) return []
+  const requirements = []
+  const add = (capability, family) => {
+    if (!enabled(profile, capability)) return
+    for (const [key, expected] of Object.entries(baseline.families?.[family] ?? {})) requirements.push({ capability, key, expected })
+  }
+  add('webControlPlane', 'web')
+  if (enabled(profile, 'webControlPlane') && profile.environments?.production?.hosting === 'cloudflare-opennext') add('webControlPlane', 'cloudflare-opennext')
+  add('agents', 'agents')
+  add('jobs', 'jobs')
+  if (enabled(profile, 'webControlPlane') && profile.project?.access !== 'public') add('webControlPlane', 'identity')
+  if (enabled(profile, 'sandbox') && control(profile, 'sandbox', 'provider') === 'cloudflare-sandbox') add('sandbox', 'sandbox-cloudflare')
+  return requirements
+}
+
+function profileRelativeName(path, projectRoot) {
+  const absolute = resolve(path)
+  if (projectRoot) {
+    const relativePath = relative(resolve(projectRoot), absolute).split(sep).join('/')
+    if (!relativePath.startsWith('..')) return relativePath
+  }
+  return basename(dirname(absolute)) === '.vegastack' ? `.vegastack/${basename(absolute)}` : basename(absolute)
+}
+
+export async function validateProfile(path, options = {}) {
+  const diagnostics = []
+  const profileRel = profileRelativeName(path, options.projectRoot)
+  let profile
+  try { profile = await readJsonYaml(path) } catch (error) {
+    return { profile: null, errors: [error.message], diagnostics: [diag('FOUND-001', 'profile.parse', profileRel, error.message, false)], exceptions: [] }
+  }
+  if (profile.schemaVersion === 2) {
+    const message = 'schemaVersion 2 is obsolete; run profile-tool.mjs migrate-v2 <profile> for a deterministic read-only v3 draft, then confirm project facts'
+    return { profile, errors: [message], diagnostics: [diag('FOUND-001', 'profile.schema-version', profileRel, message, false)], exceptions: [] }
+  }
+  const schema = JSON.parse(await readFile(schemaPath, 'utf8'))
+  for (const message of validateJsonSchema(schema, profile)) diagnostics.push(diag('FOUND-001', 'profile.schema', profileRel, message, false))
+  const profileDirectory = dirname(resolve(path))
+  const projectRoot = resolve(options.projectRoot ?? (basename(profileDirectory) === '.vegastack' ? dirname(profileDirectory) : process.cwd()))
+  const compatibility = JSON.parse(await readFile(compatibilityPath, 'utf8'))
+  const knownRules = await canonicalRuleIds()
+  const now = options.now ? new Date(options.now) : new Date()
+  const exceptionStates = await validateExceptions(profile, projectRoot, now, knownRules)
+  for (const state of exceptionStates.filter(item => !item.valid)) diagnostics.push(diag('FOUND-002', 'exception.validity', profileRel, `${state.exception?.id ?? 'unknown'}: ${state.reasons.join('; ')}`, false))
+
+  if (profile.profileStatus !== 'confirmed') diagnostics.push(diag('FOUND-001', 'profile.confirmed', profileRel, 'profileStatus must be confirmed before CI; the bundled profile is an intentionally incomplete draft', false))
+  if (String(profile.project?.name ?? '').startsWith('REQUIRED-')) diagnostics.push(diag('FOUND-001', 'profile.project-name', profileRel, 'replace the REQUIRED project name with a confirmed fact', false))
+  const baseline = compatibility.baselines?.[profile.foundation?.baseline]
+  if (!baseline) diagnostics.push(diag('PKG-003', 'foundation.baseline', profileRel, `unknown foundation baseline ${profile.foundation?.baseline}`))
+  else if (profile.foundation?.adoption !== baseline.state) diagnostics.push(diag('PKG-003', 'foundation.adoption', profileRel, `baseline ${profile.foundation.baseline} has state ${baseline.state}, not ${profile.foundation?.adoption}`))
+  else if (baseline.state !== 'supported') diagnostics.push(diag('PKG-003', 'foundation.non-supported-adoption', profileRel, `${baseline.state} baseline adoption requires scoped project-owner ADR and qualification evidence`))
+
+  for (const [name, capability] of Object.entries(profile.capabilities ?? {})) {
+    if (capability?.status !== 'enabled') continue
+    for (const [key, version] of Object.entries(capability.versions ?? {})) if (!exactVersion.test(String(version))) diagnostics.push(diag('PKG-003', `version.${name}.${key}`, profileRel, `${name}.versions.${key} must be an exact version`))
+    if (capability.ownership === 'owned') for (const root of capability.sourceRoots ?? []) {
+      const full = resolve(projectRoot, root)
+      try {
+        if (relative(projectRoot, full).startsWith('..')) throw new Error('outside project')
+        if ((await lstat(full)).isSymbolicLink()) throw new Error('symlink')
+        if (!(await lstat(full)).isDirectory()) throw new Error('not a directory')
+      } catch (error) { diagnostics.push(diag('FOUND-004', `capability.${name}.source-root`, root, `owned enabled capability ${name} source root is unavailable: ${error.message}`)) }
+    }
+  }
+  const separatedRuntimes = new Set(['webControlPlane', 'agents', 'jobs'])
+  const ownedRoots = Object.entries(profile.capabilities ?? {}).flatMap(([name, cap]) => separatedRuntimes.has(name) && cap?.status === 'enabled' && cap?.ownership === 'owned' ? (cap.sourceRoots ?? []).map(root => [name, root]) : [])
+  for (let left = 0; left < ownedRoots.length; left += 1) for (let right = left + 1; right < ownedRoots.length; right += 1) {
+    const [leftOwner, leftRoot] = ownedRoots[left]
+    const [rightOwner, rightRoot] = ownedRoots[right]
+    if (leftOwner !== rightOwner && (leftRoot === rightRoot || leftRoot.startsWith(`${rightRoot}/`) || rightRoot.startsWith(`${leftRoot}/`))) diagnostics.push(diag('RUN-003', 'capability.source-root-overlap', profileRel, `owned source roots overlap between ${leftOwner} and ${rightOwner}: ${leftRoot} / ${rightRoot}`))
+  }
+
+  for (const item of requiredFamilyVersions(profile, compatibility)) {
+    const actual = profile.capabilities?.[item.capability]?.versions?.[item.key]
+    if (actual !== item.expected) diagnostics.push(diag('PKG-003', `version.${item.capability}.${item.key}`, profileRel, `${item.capability}.versions.${item.key} must equal supported baseline ${item.expected}; lag/advance requires a scoped project ADR`))
+  }
+
+  if (enabled(profile, 'flutter')) {
+    if (!enabled(profile, 'webControlPlane')) diagnostics.push(diag('MOB-002', 'flutter.api-provider', profileRel, 'Flutter requires an enabled REST/OpenAPI provider capability'))
+    if (control(profile, 'flutter', 'delegatedOAuthPkce') !== true) diagnostics.push(diag('MOB-001', 'flutter.oauth-pkce', profileRel, 'Flutter requires delegated OAuth/OIDC code with S256 PKCE'))
+    if (control(profile, 'flutter', 'generatedRestClient') !== true || control(profile, 'webControlPlane', 'openapiGenerated') !== true) diagnostics.push(diag('MOB-002', 'flutter.generated-client', profileRel, 'Flutter requires deterministic generated REST/OpenAPI client consumption'))
+  }
+  if (enabled(profile, 'agents')) {
+    if (control(profile, 'agents', 'workflowWorld') !== 'postgres' || control(profile, 'agents', 'agentRun') !== true) diagnostics.push(diag('DUR-001', 'agents.durable-owner', profileRel, 'Agents require qualified EVE/Postgres World and AgentRun'))
+    if (profile.capabilities.agents.ownership === 'owned' && (!control(profile, 'agents', 'workflowDatabaseOwner') || !control(profile, 'agents', 'agentRunOwner'))) diagnostics.push(diag('DUR-001', 'agents.storage-ownership', profileRel, 'Owned agents must declare the Workflow PostgreSQL and AgentRun durable owners'))
+    const admission = control(profile, 'agents', 'admission')
+    if (admission === 'pg-boss' && (!enabled(profile, 'jobs') || profile.capabilities.jobs.ownership !== 'owned' || !(control(profile, 'jobs', 'roles') ?? []).includes('agent-admission'))) diagnostics.push(diag('DUR-003', 'agents.admission', profileRel, 'owned agent admission requires owned pg-boss jobs with agent-admission role'))
+    if (admission === 'shared-contract' && !profile.capabilities.agents.contract && !profile.capabilities.jobs?.contract) diagnostics.push(diag('DUR-003', 'agents.admission', profileRel, 'shared admission requires an explicit qualified service contract'))
+    if (!['pg-boss', 'shared-contract'].includes(admission)) diagnostics.push(diag('DUR-003', 'agents.admission', profileRel, 'agents must declare pg-boss or shared-contract admission'))
+  }
+  if (enabled(profile, 'jobs') && profile.capabilities.jobs.ownership === 'owned' && !control(profile, 'jobs', 'databaseOwner')) diagnostics.push(diag('DUR-003', 'jobs.database-owner', profileRel, 'Owned pg-boss jobs must declare their PostgreSQL owner'))
+  if (enabled(profile, 'knowledge') && profile.capabilities.knowledge.ownership === 'owned') {
+    if (!control(profile, 'knowledge', 'postgresOwner')) diagnostics.push(diag('DATA-002', 'knowledge.storage-owner', profileRel, 'Owned knowledge must declare its PostgreSQL/pgvector owner'))
+    if (control(profile, 'knowledge', 'binaryObjects') === true && !control(profile, 'knowledge', 'objectStorageOwner')) diagnostics.push(diag('DATA-002', 'knowledge.object-storage-owner', profileRel, 'Knowledge with binary objects must declare the object-storage owner'))
+  }
+  for (const name of ['connectors', 'modelRouting']) if (enabled(profile, name) && control(profile, name, 'credentialBearing') === true && !enabled(profile, 'secrets')) diagnostics.push(diag('SEC-002', 'secrets.dependency', profileRel, `Credential-bearing ${name} requires an enabled production secret-custody capability`))
+  if (enabled(profile, 'enterpriseIdentity') && control(profile, 'enterpriseIdentity', 'scim') === true && !enabled(profile, 'secrets')) diagnostics.push(diag('SEC-002', 'secrets.dependency', profileRel, 'SCIM requires an enabled production secret-custody capability'))
+  if (enabled(profile, 'notifications') && !control(profile, 'notifications', 'durableIntentOwner')) diagnostics.push(diag('RT-005', 'notifications.durable-intent-owner', profileRel, 'Notifications must declare the durable notification-intent owner'))
+  if (control(profile, 'agents', 'untrustedExecution') === true) {
+    if (!enabled(profile, 'sandbox')) diagnostics.push(diag('SBX-001', 'sandbox.activation', profileRel, 'untrusted execution activates the sandbox capability'))
+    if (control(profile, 'sandbox', 'trustedBroker') !== true) diagnostics.push(diag('SBX-002', 'sandbox.trusted-broker', profileRel, 'untrusted execution requires a trusted capability broker'))
+  }
+  if (enabled(profile, 'sandbox')) {
+    if (control(profile, 'sandbox', 'egress') !== 'deny-by-default') diagnostics.push(diag('SBX-003', 'sandbox.egress', profileRel, 'sandbox egress must be deny-by-default'))
+    if (control(profile, 'sandbox', 'databaseCredentials') !== false) diagnostics.push(diag('SBX-002', 'sandbox.credentials', profileRel, 'sandboxes must not receive database credentials'))
+  }
+  if (enabled(profile, 'enterpriseIdentity') && control(profile, 'enterpriseIdentity', 'scim') === true) {
+    if (control(profile, 'enterpriseIdentity', 'organizationMapping') !== true || control(profile, 'enterpriseIdentity', 'deprovisioning') !== true) diagnostics.push(diag('AUTH-006', 'identity.scim-deprovisioning', profileRel, 'SCIM requires organization mapping and complete deprovisioning'))
+  }
+  if (enabled(profile, 'webControlPlane')) {
+    if (profile.environments?.production?.hosting === 'cloudflare-opennext' && profile.capabilities.webControlPlane.placement !== 'open-next-worker') diagnostics.push(diag('HOST-004', 'hosting.web-placement', profileRel, 'Cloudflare/OpenNext requires web placement open-next-worker'))
+    if (profile.project?.access !== 'public' && control(profile, 'webControlPlane', 'secureCookies') !== true) diagnostics.push(diag('AUTH-003', 'auth.secure-cookies', profileRel, 'authenticated web access requires secure cookies'))
+    if (profile.project?.access !== 'public' && profile.capabilities.webControlPlane.ownership === 'owned' && !enabled(profile, 'secrets')) diagnostics.push(diag('SEC-002', 'secrets.activation', profileRel, 'owned authenticated web production activates secret custody'))
+    if (enabled(profile, 'flutter') && (control(profile, 'webControlPlane', 'canonicalApi') !== 'rest-openapi' || control(profile, 'webControlPlane', 'openapiGenerated') !== true)) diagnostics.push(diag('API-002', 'api.generated-contract', profileRel, 'Flutter requires canonical generated REST/OpenAPI'))
+  }
+  if (profile.environments?.production?.hosting === 'cloudflare-opennext') for (const name of ['agents', 'jobs']) {
+    const cap = profile.capabilities?.[name]
+    if (cap?.status === 'enabled' && cap.ownership === 'owned' && !['node-service', 'oci-container'].includes(cap.placement)) diagnostics.push(diag(name === 'agents' ? 'RUN-001' : 'RUN-002', `hosting.${name}-placement`, profileRel, `owned ${name} must use external long-running Node/OCI placement outside OpenNext`))
+  }
+  if (enabled(profile, 'secrets') && profile.capabilities.secrets.ownership === 'owned' && control(profile, 'secrets', 'provider') !== 'openbao') diagnostics.push(diag('SEC-002', 'secrets.production-provider', profileRel, 'owned production secret custody requires OpenBao'))
+
+  const errors = diagnostics.map(item => `${item.rule}/${item.control}: ${item.message}`)
+  return { profile, errors, diagnostics, exceptions: exceptionStates }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  const argument = process.argv.slice(2).find(value => !value.startsWith('-'))
+  let path = argument ? resolve(argument) : null
+  if (!path) {
+    const discovered = await resolveProfile(process.cwd())
+    if (!discovered) { console.error('error: no .vegastack/architecture.json (or legacy .yaml) profile found; pass a path explicitly'); process.exit(2) }
+    if (discovered.legacy) console.error(`deprecation: ${discovered.relative} uses the legacy .yaml name for a JSON document; rename to .vegastack/architecture.json`)
+    path = discovered.path
+  }
+  const json = process.argv.includes('--json')
+  const result = await validateProfile(path)
+  if (json) console.log(JSON.stringify({ path, valid: result.errors.length === 0, diagnostics: result.diagnostics, exceptions: result.exceptions }, null, 2))
+  else if (result.errors.length) for (const error of result.errors) console.error(`FAIL profile: ${error}`)
+  else console.log(`validate-profile: valid ${path}`)
+  if (result.errors.length) process.exitCode = 1
+}