@vegastack/skills 0.2.0 → 0.4.0

package/skill/arch-guardian/refresh/sources.json

@@ -153,7 +153,8 @@
         "changelog": "https://github.com/vercel/next.js/releases",
         "package": "https://www.npmjs.com/package/next/v/16.3.0",
         "repository": "https://github.com/vercel/next.js/tree/d73f5622e226358dcef8cf7a8a373333ff265ae7",
-        "security": "https://github.com/vercel/next.js/security"
+        "security": "https://github.com/vercel/next.js/security",
+        "llms": "https://nextjs.org/docs/llms.txt"
       },
       "versionDetection": {
         "type": "npm",
@@ -227,7 +228,8 @@
         "docsIndex": "https://developers.cloudflare.com/workers/",
         "api": "https://developers.cloudflare.com/api/",
         "changelog": "https://developers.cloudflare.com/changelog/",
-        "security": "https://www.cloudflare.com/trust-hub/"
+        "security": "https://www.cloudflare.com/trust-hub/",
+        "llms": "https://developers.cloudflare.com/llms.txt"
       },
       "versionDetection": {
         "type": "http-hash-and-changelog"
@@ -265,7 +267,8 @@
         "changelog": "https://developers.cloudflare.com/changelog/",
         "package": "https://www.npmjs.com/package/@cloudflare/sandbox/v/0.12.4",
         "repository": "https://github.com/cloudflare/sandbox-sdk/tree/798afcf33ead69fdbfb6598ca345f396deb4d6b2",
-        "security": "https://github.com/cloudflare/sandbox-sdk/security"
+        "security": "https://github.com/cloudflare/sandbox-sdk/security",
+        "llms": "https://developers.cloudflare.com/llms.txt"
       },
       "versionDetection": {
         "type": "npm",
@@ -302,7 +305,8 @@
         "primary": "https://developers.cloudflare.com/hyperdrive/concepts/connection-pooling/",
         "docsIndex": "https://developers.cloudflare.com/hyperdrive/",
         "api": "https://developers.cloudflare.com/api/resources/hyperdrive/",
-        "changelog": "https://developers.cloudflare.com/changelog/"
+        "changelog": "https://developers.cloudflare.com/changelog/",
+        "llms": "https://developers.cloudflare.com/llms.txt"
       },
       "versionDetection": {
         "type": "http-hash-and-changelog"
@@ -337,7 +341,8 @@
         "docsIndex": "https://developers.cloudflare.com/ai-gateway/",
         "api": "https://developers.cloudflare.com/api/resources/ai-gateway/",
         "changelog": "https://developers.cloudflare.com/changelog/",
-        "security": "https://www.cloudflare.com/trust-hub/"
+        "security": "https://www.cloudflare.com/trust-hub/",
+        "llms": "https://developers.cloudflare.com/llms.txt"
       },
       "versionDetection": {
         "type": "http-hash-and-changelog"
@@ -372,7 +377,8 @@
         "changelog": "https://modal.com/docs/reference/changelog",
         "package": "https://pypi.org/project/modal/1.5.3/",
         "repository": "https://github.com/modal-labs/modal-client/tree/e8454377aa7c94e562d525c700a95a23b3d8838a",
-        "security": "https://modal.com/security"
+        "security": "https://modal.com/security",
+        "llms": "https://modal.com/llms.txt"
       },
       "versionDetection": {
         "type": "pypi",
@@ -415,7 +421,8 @@
         "changelog": "https://better-auth.com/changelog",
         "package": "https://www.npmjs.com/package/better-auth/v/1.6.26",
         "repository": "https://github.com/better-auth/better-auth/tree/a16b30e8437927c08350194000178073b06af8cf",
-        "security": "https://github.com/better-auth/better-auth/blob/a16b30e8437927c08350194000178073b06af8cf/SECURITY.md"
+        "security": "https://github.com/better-auth/better-auth/blob/a16b30e8437927c08350194000178073b06af8cf/SECURITY.md",
+        "llms": "https://better-auth.com/llms.txt"
       },
       "versionDetection": {
         "type": "npm-suite",
@@ -649,7 +656,8 @@
         "changelog": "https://github.com/vercel/turborepo/releases",
         "package": "https://www.npmjs.com/package/turbo",
         "repository": "https://github.com/vercel/turborepo",
-        "security": "https://github.com/vercel/turborepo/security"
+        "security": "https://github.com/vercel/turborepo/security",
+        "llms": "https://turborepo.dev/llms.txt"
       },
       "versionDetection": {
         "type": "npm",
@@ -683,7 +691,8 @@
         "api": "https://api.flutter.dev/",
         "changelog": "https://docs.flutter.dev/release/release-notes",
         "repository": "https://github.com/flutter/flutter",
-        "security": "https://github.com/flutter/flutter/security"
+        "security": "https://github.com/flutter/flutter/security",
+        "llms": "https://docs.flutter.dev/llms.txt"
       },
       "versionDetection": {
         "type": "release-index"
@@ -777,8 +786,8 @@
       "versionDetection": {
         "type": "http-hash-and-changelog"
       },
-      "retrievedAt": "2026-08-08T07:53:01.687Z",
-      "checksum": "9d428c76f42eafa6cd895e29bc54cd7b2ba0fa067c63eef457d6cf1a519b1b71",
+      "retrievedAt": "2026-08-08T10:20:35.016Z",
+      "checksum": "3e1d7ed893bbc41eff69d7009bd1269c811ea773a9edfb2a05e9e3c68af91343",
       "previousRetrievalChecksum": "d8117a391c5875a7b4d352a3f8b8b89ad12e6617a91038228f7279c732d0cd98",
       "topics": [
         "notifications",
@@ -994,7 +1003,8 @@
         "api": "https://bun.sh/docs/api",
         "changelog": "https://bun.sh/blog",
         "repository": "https://github.com/oven-sh/bun",
-        "security": "https://github.com/oven-sh/bun/security"
+        "security": "https://github.com/oven-sh/bun/security",
+        "llms": "https://bun.sh/llms.txt"
       },
       "versionDetection": {
         "type": "runtime-and-github-release"
@@ -1026,7 +1036,8 @@
         "docsIndex": "https://modelcontextprotocol.io/docs",
         "changelog": "https://modelcontextprotocol.io/specification/versioning",
         "repository": "https://github.com/modelcontextprotocol/modelcontextprotocol",
-        "security": "https://modelcontextprotocol.io/specification/2026-07-28/basic/security_best_practices"
+        "security": "https://modelcontextprotocol.io/specification/2026-07-28/basic/security_best_practices",
+        "llms": "https://modelcontextprotocol.io/llms.txt"
       },
       "versionDetection": {
         "type": "spec-version"
@@ -1058,7 +1069,8 @@
         "changelog": "https://github.com/vercel/ai/releases",
         "package": "https://www.npmjs.com/package/ai",
         "repository": "https://github.com/vercel/ai",
-        "security": "https://github.com/vercel/ai/security"
+        "security": "https://github.com/vercel/ai/security",
+        "llms": "https://ai-sdk.dev/llms.txt"
       },
       "versionDetection": {
         "type": "npm",

package/skill/arch-guardian/scripts/lib.mjs

@@ -1,8 +1,7 @@
 import { createHash } from 'node:crypto'
 import { lstat, readFile, readdir } from 'node:fs/promises'
-import { join, relative, sep } from 'node:path'
+import { join, relative } from 'node:path'
 
-export const LABELS = ['OBSERVED', 'DOCUMENTED', 'REPRODUCED', 'INFERRED', 'RECOMMENDED', 'NOT VERIFIED']
 export const sha256 = body => createHash('sha256').update(body).digest('hex')
 
 // Canonical profile basename first; legacy name accepted with a deprecation notice at call sites.
@@ -47,11 +46,3 @@ export async function listFiles(root, predicate = () => true) {
   return output.sort((a, b) => relative(root, a).localeCompare(relative(root, b)))
 }
 
-export function slashRelative(root, path) {
-  return relative(root, path).split(sep).join('/')
-}
-
-export function issue(status, rule, control, message, evidence, extra = {}) {
-  const severity = status === 'FAIL' ? 'fail' : status === 'EXCEPTED' ? 'accepted-risk' : status === 'NOT_VERIFIED' ? 'warning' : 'pass'
-  return { status, severity, rule, control, message, verificationType: extra.verificationType ?? 'static-sentinel', ...(evidence ? { evidence, path: evidence.path } : {}), ...extra }
-}

package/skill/arch-guardian/scripts/profile-tool.mjs

@@ -5,18 +5,21 @@ import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep }
 import { pathToFileURL } from 'node:url'
 import { pathExists, readJsonYaml } from './lib.mjs'
 
-const capabilityNames = ['webControlPlane', 'flutter', 'agents', 'jobs', 'sandbox', 'connectors', 'knowledge', 'modelRouting', 'enterpriseIdentity', 'realtime', 'notifications', 'secrets']
+const capabilityNames = ['web', 'flutter', 'agents', 'jobs', 'sandbox', 'connectors', 'knowledge', 'models', 'enterprise-identity', 'realtime', 'notifications']
 const observedListCap = 25
+// Observation patterns are heuristic evidence, never proof. `secrets` is observed as advisory
+// evidence but is not a declarable capability — secret custody guidance activates whenever
+// production secrets exist.
 const patterns = {
-  webControlPlane: /(?:next|@opennextjs\/cloudflare)/i,
+  web: /(?:next|@opennextjs\/cloudflare)/i,
   flutter: /(?:pubspec\.yaml|package:flutter)/i,
   agents: /(?:\beve\b|@workflow\/world|AgentRun)/i,
   jobs: /(?:pg-boss|PgBoss)/i,
   sandbox: /(?:@cloudflare\/sandbox|SandboxProvider|enableInternet)/i,
   connectors: /(?:\bMCP\b|webhook|connector)/i,
   knowledge: /(?:pgvector|embedding|\bknowledge\b)/i,
-  modelRouting: /(?:ai-gateway|generateText|streamText|BYOK)/i,
-  enterpriseIdentity: /(?:\bSCIM\b|\bSSO\b|saml)/i,
+  models: /(?:ai-gateway|generateText|streamText|BYOK)/i,
+  'enterprise-identity': /(?:\bSCIM\b|\bSSO\b|saml)/i,
   realtime: /(?:EventSource|text\/event-stream|WebSocket)/i,
   notifications: /(?:firebase_messaging|APNs|notification)/i,
   secrets: /(?:OPENBAO|VAULT_ADDR|CLIENT_SECRET|DATABASE_URL)/i
@@ -40,18 +43,17 @@ async function inspectableFiles(root) {
 
 function baseDraft() {
   return {
-    schemaVersion: 3,
-    profileStatus: 'draft',
-    foundation: { version: '0.3.0', baseline: 'vs-2026-08-07', adoption: 'supported' },
-    project: { name: 'REQUIRED-CONFIRMED-PROJECT-NAME', kind: 'REQUIRED-CONFIRMED-PROJECT-KIND', lifecycle: 'brownfield', access: 'REQUIRED-CONFIRMED-ACCESS', tenancy: 'REQUIRED-CONFIRMED-TENANCY' },
-    environments: { production: { hosting: 'REQUIRED-CONFIRMED-PRODUCTION-TARGET' }, localDevelopment: { trusted: true, allowances: [] } },
-    capabilities: Object.fromEntries(capabilityNames.map(name => [name, { status: 'disabled', ownership: 'not-applicable' }])),
-    exceptions: []
+    schemaVersion: 4,
+    foundationVersion: '0.4.0',
+    project: { name: 'REQUIRED-CONFIRMED-PROJECT-NAME', kind: 'REQUIRED-CONFIRMED-KIND', tier: 'REQUIRED-CONFIRMED-TIER', tenancy: 'REQUIRED-CONFIRMED-TENANCY' },
+    hosting: 'REQUIRED-CONFIRMED-HOSTING',
+    capabilities: [],
+    notes: []
   }
 }
 
 // Only literally exact versions are recorded as facts; ranges ("^1.2.3") are not laundered into
-// exact pins — the draft records them as unconfirmed instead.
+// exact pins — they stay observational.
 function exact(value) {
   const normalized = String(value ?? '').trim().replace(/^v/, '')
   return /^\d+\.\d+(?:\.\d+)?(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(normalized) ? normalized : null
@@ -69,7 +71,7 @@ async function inspect(root) {
       for (const [name, value] of Object.entries({ ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) })) if (exact(value)) packageVersions[name] = exact(value)
     } catch { /* malformed manifests remain observational unknowns */ }
   }
-  const observed = Object.fromEntries(capabilityNames.map(name => [name, []]))
+  const observed = Object.fromEntries(Object.keys(patterns).map(name => [name, []]))
   for (const path of files.filter(path => !/[\\/]\.vegastack[\\/]/.test(path) && (['.ts', '.tsx', '.js', '.mjs', '.cjs', '.json', '.yaml', '.yml', '.toml', '.sql', '.dart'].includes(extname(path)) || basename(path) === 'pubspec.yaml'))) {
     const rel = relative(root, path).split(sep).join('/')
     let body = ''
@@ -77,27 +79,14 @@ async function inspect(root) {
     for (const [name, pattern] of Object.entries(patterns)) if (pattern.test(`${rel}\n${body}`)) observed[name].push(rel)
   }
   const profile = baseDraft()
-  for (const [name, evidence] of Object.entries(observed)) if (evidence.length) {
-    const sourceRoot = evidence[0].includes('/') ? evidence[0].split('/').slice(0, -1).join('/') : '.'
-    const versions = {}
-    const candidates = {
-      webControlPlane: [['next', 'next'], ['openNext', '@opennextjs/cloudflare']],
-      agents: [['eve', 'eve'], ['workflowPostgres', '@workflow/world-postgres']],
-      jobs: [['pgBoss', 'pg-boss']],
-      sandbox: [['cloudflareSandbox', '@cloudflare/sandbox']]
-    }[name] ?? []
-    for (const [key, pkg] of candidates) if (packageVersions[pkg]) versions[key] = packageVersions[pkg]
-    profile.capabilities[name] = { status: 'enabled', ownership: 'REQUIRED-CONFIRMED-OWNERSHIP', versions: Object.keys(versions).length ? versions : { unconfirmed: 'REQUIRED-EXACT-VERSION' }, placement: 'REQUIRED-CONFIRMED-PLACEMENT', sourceRoots: [sourceRoot], controls: { observedSourceRoots: evidence } }
-  }
+  profile.capabilities = capabilityNames.filter(name => observed[name].length)
   const artifacts = ['.vegastack/architecture.json']
-  if (Object.values(profile.capabilities).some(item => item.status === 'enabled')) artifacts.push('docs/architecture/service-design.md')
-  if (profile.environments.production.hosting !== 'none') artifacts.push('docs/architecture/deployment-review.md')
-  if (['connectors', 'sandbox', 'agents'].some(name => profile.capabilities[name].status === 'enabled')) artifacts.push('docs/architecture/threat-model.md')
+  if (['connectors', 'sandbox', 'agents'].some(name => observed[name].length)) artifacts.push('docs/architecture/threat-model.md')
   const after = await inspectableFiles(root)
   let changed = after.length !== before.size
   for (const path of after) if (!before.has(path) || before.get(path) !== (await lstat(path)).mtimeMs) changed = true
   if (changed) throw new Error('inspection mutation guard detected a changed file inventory')
-  return { mode: 'brownfield-observed', mutated: false, observed, packageVersions, profileDraft: profile, relevantArtifacts: artifacts, caveats: ['Detection is heuristic and does not prove absence, ownership, placement, compliance, runtime behavior, or project intent. Every REQUIRED field must be confirmed before use.'] }
+  return { mode: 'brownfield-observed', mutated: false, observed, packageVersions, profileDraft: profile, relevantArtifacts: artifacts, caveats: ['Detection is heuristic and does not prove absence, placement, compliance, runtime behavior, or project intent. Every REQUIRED field must be confirmed before use.'] }
 }
 
 // Compact context-friendly view for interactive agent use; --json prints the full result.
@@ -117,26 +106,31 @@ function capObserved(result) {
 }
 
 function fromAnswers(answers) {
-  if (answers.schemaVersion === 3) return answers
+  if (answers.schemaVersion === 4) return answers
   const profile = baseDraft()
-  for (const key of ['profileStatus', 'project', 'environments', 'capabilities', 'data', 'objectives', 'exceptions']) if (answers[key] !== undefined) profile[key] = answers[key]
+  for (const key of ['project', 'hosting', 'capabilities', 'notes', 'foundationVersion']) if (answers[key] !== undefined) profile[key] = answers[key]
   return profile
 }
 
-function migrateV2(old) {
-  if (old.schemaVersion !== 2) throw new Error('migrate-v2 requires a schemaVersion 2 profile')
+// Deterministic v3 -> v4 migration: exceptions are dropped (the advisor records deliberate
+// deviations in notes/ADR documents, never as suppression machinery), capability detail collapses
+// to the enabled list, and versions return to lockfiles.
+const v3CapabilityMap = { webControlPlane: 'web', flutter: 'flutter', agents: 'agents', jobs: 'jobs', sandbox: 'sandbox', connectors: 'connectors', knowledge: 'knowledge', modelRouting: 'models', enterpriseIdentity: 'enterprise-identity', realtime: 'realtime', notifications: 'notifications' }
+const v3KindMap = { 'saas-product': 'saas', 'internal-product': 'internal-tool', 'public-product': 'saas', 'platform-service': 'api', 'shared-package': 'package' }
+
+function migrateV3(old) {
+  if (old.schemaVersion !== 3) throw new Error('migrate requires a schemaVersion 3 profile; older versions need a fresh v4 profile from answers')
   const profile = baseDraft()
-  profile.project = { name: old.project ?? 'REQUIRED-CONFIRMED-PROJECT-NAME', kind: 'saas-product', lifecycle: 'migration', access: 'authenticated', tenancy: old.tenancy?.storage === 'shared-schema-composite-keys' ? 'multi-tenant-shared-schema' : 'REQUIRED-CONFIRMED-TENANCY' }
-  profile.environments.production.hosting = old.hostingProfile ?? 'REQUIRED-CONFIRMED-HOSTING'
-  const owned = (versions, placement, sourceRoots, controls = {}) => ({ status: 'enabled', ownership: 'owned', versions, placement, sourceRoots, controls })
-  profile.capabilities.webControlPlane = owned({ bun: old.versions?.bun, node: old.versions?.node, next: old.versions?.next, ...(old.versions?.openNext !== 'not-applicable' ? { openNext: old.versions?.openNext } : {}), betterAuth: old.versions?.betterAuth }, old.runtimePlacement?.next, old.sourceRoots?.next, { canonicalApi: old.capabilities?.api?.canonical, openapiGenerated: old.capabilities?.api?.openapiGenerated, secureCookies: true })
-  profile.capabilities.flutter = owned({ flutter: 'REQUIRED-EXACT-VERSION' }, old.runtimePlacement?.flutter, ['REQUIRED-CONFIRMED-FLUTTER-ROOT'], { delegatedOAuthPkce: old.identity?.delegated === 'oauth2.1-oidc-code-pkce', generatedRestClient: old.capabilities?.api?.openapiGenerated === true })
-  profile.capabilities.agents = owned({ eve: old.versions?.eve, workflowWorldContract: old.versions?.workflowWorldContract, workflowLocal: old.versions?.workflowLocal, workflowPostgres: old.versions?.workflowPostgres, node: old.versions?.node }, old.runtimePlacement?.eve, old.sourceRoots?.eve, { workflowWorld: 'postgres', agentRun: true, admission: 'pg-boss' })
-  profile.capabilities.jobs = owned({ pgBoss: old.versions?.pgBoss, postgres: old.versions?.postgres }, old.runtimePlacement?.jobs, old.sourceRoots?.jobs, { roles: old.capabilities?.jobs?.roles ?? [] })
-  profile.capabilities.sandbox = owned({ provider: 'REQUIRED-EXACT-VERSION' }, old.runtimePlacement?.sandboxBroker, ['REQUIRED-CONFIRMED-SANDBOX-ROOT'], { provider: old.capabilities?.sandbox?.provider, egress: old.capabilities?.sandbox?.egress, databaseCredentials: old.capabilities?.sandbox?.databaseCredentials, trustedBroker: true })
-  if (old.capabilities?.secrets === 'openbao') profile.capabilities.secrets = owned({ openbao: 'REQUIRED-EXACT-VERSION' }, 'external-service', ['REQUIRED-CONFIRMED-SECRETS-CONFIG-ROOT'], { provider: 'openbao' })
-  profile.exceptions = []
-  return { profile, guidance: ['The v2 format implied a full platform, so all implied capabilities are enabled in this draft.', 'Confirm project kind/access/tenancy, Flutter and sandbox roots/versions, controls, capability ownership, data/objectives, and migrate each exception to exact v3 rule/control/path scope.', 'No source file or old profile was changed.'] }
+  profile.project = {
+    name: old.project?.name ?? 'REQUIRED-CONFIRMED-PROJECT-NAME',
+    kind: v3KindMap[old.project?.kind] ?? 'REQUIRED-CONFIRMED-KIND',
+    tier: 'REQUIRED-CONFIRMED-TIER',
+    tenancy: old.project?.tenancy ?? 'REQUIRED-CONFIRMED-TENANCY'
+  }
+  profile.hosting = old.environments?.production?.hosting ?? 'REQUIRED-CONFIRMED-HOSTING'
+  profile.capabilities = Object.entries(old.capabilities ?? {}).filter(([, value]) => value?.status === 'enabled').map(([name]) => v3CapabilityMap[name]).filter(Boolean)
+  profile.notes = (old.exceptions ?? []).map(exception => `migrated deviation (was exception ${exception.id} on ${exception.ruleId}): ${exception.decision ?? exception.rationale ?? 'see original ADR'}`)
+  return { profile, guidance: ['Confirm the tier deliberately — it decides which concerns apply, not which tools.', 'v3 exceptions were converted to notes; the advisor has no suppression machinery.', 'Versions now come from lockfiles at advice time.', 'No source file or old profile was changed.'] }
 }
 
 async function assertNoSymlink(path) {
@@ -199,18 +193,18 @@ function confinedOutput(dir, output) {
 
 async function main() {
   const options = parse(process.argv.slice(2))
-  if (options.command === 'help') return console.log('Usage: profile-tool.mjs inspect [DIR] [--json] | scaffold ANSWERS.json --dir DIR [--write] [--force] [--output PATH] | migrate-v2 PROFILE --dir DIR [--write] [--force] [--output PATH]\n\ninspect prints a compact summary by default; --json prints the full draft and evidence.\nscaffold answers format: see assets/answers-example.json next to this skill.\nWrites are atomic, refuse symlinks, stay inside --dir, and require --force to replace differing content.')
+  if (options.command === 'help') return console.log('Usage: profile-tool.mjs inspect [DIR] [--json] | scaffold ANSWERS.json --dir DIR [--write] [--force] [--output PATH] | migrate PROFILE --dir DIR [--write] [--force] [--output PATH]\n\ninspect prints a compact summary by default; --json prints the full draft and evidence.\nscaffold answers format: see assets/answers-example.json next to this skill.\nmigrate converts a v3 profile to a v4 draft (exceptions become notes).\nWrites are atomic, refuse symlinks, stay inside --dir, and require --force to replace differing content.')
   if (options.command === 'inspect') {
     const root = resolve(options.input ?? options.dir)
     const result = await inspect(root)
     return console.log(JSON.stringify(options.json ? capObserved(result) : summarizeInspection(result), null, 2))
   }
-  if (!['scaffold', 'migrate-v2'].includes(options.command) || !options.input) throw new Error('A supported command and input file are required')
+  if (!['scaffold', 'migrate'].includes(options.command) || !options.input) throw new Error('A supported command and input file are required')
   const source = resolve(options.input)
   const parsed = await readJsonYaml(source)
-  const result = options.command === 'migrate-v2' ? migrateV2(parsed) : { profile: fromAnswers(parsed), guidance: ['Generated only from supplied answers; confirm draft facts before CI.'] }
+  const result = options.command === 'migrate' ? migrateV3(parsed) : { profile: fromAnswers(parsed), guidance: ['Generated only from supplied answers; confirm draft facts before relying on them.'] }
   const body = `${JSON.stringify(result.profile, null, 2)}\n`
-  const defaultOutput = options.command === 'migrate-v2' ? '.vegastack/architecture.v3-draft.json' : '.vegastack/architecture.json'
+  const defaultOutput = options.command === 'migrate' ? '.vegastack/architecture.v4-draft.json' : '.vegastack/architecture.json'
   const output = confinedOutput(options.dir, options.output ?? defaultOutput)
   const payload = { mode: options.write ? 'authorized-write' : 'dry-run', output, profile: result.profile, guidance: result.guidance }
   if (!options.write) return console.log(JSON.stringify(payload, null, 2))
@@ -220,4 +214,4 @@ async function main() {
 
 if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) main().catch(error => { console.error(`error: ${error.message}`); process.exitCode = 1 })
 
-export { inspect, migrateV2, fromAnswers, atomicWrite }
+export { inspect, migrateV3, fromAnswers, atomicWrite }

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

@@ -13,7 +13,7 @@ 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(['agentskills.io', 'ai-sdk.dev', 'ai.google.dev', 'api.flutter.dev', 'aws.amazon.com', 'better-auth.com', 'bun.sh', 'code.claude.com', 'developer.apple.com', 'developers.cloudflare.com', 'developers.openai.com', 'docs.aws.amazon.com', 'docs.flutter.dev', 'firebase.google.com', 'git.postgresql.org', 'github.com', 'hermes-agent.nousresearch.com', 'learn.chatgpt.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'])
+const approvedHosts = new Set(['agentskills.io', 'ai-sdk.dev', 'ai.google.dev', 'api.flutter.dev', 'api.osv.dev', 'aws.amazon.com', 'better-auth.com', 'bun.sh', 'code.claude.com', 'developer.apple.com', 'developers.cloudflare.com', 'developers.openai.com', 'docs.aws.amazon.com', 'docs.flutter.dev', 'firebase.google.com', 'git.postgresql.org', 'github.com', 'hermes-agent.nousresearch.com', 'learn.chatgpt.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()
@@ -22,7 +22,7 @@ function flagValue(argv, flag) {
 }
 
 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() }
+  const result = { registry: defaultRegistry, cache: '.vegastack/evidence-cache.json', report: '.vegastack/evidence-drift.json', topics: [], offline: false, acceptBaselines: false, now: new Date().toISOString(), compatibility: join(skillRoot, 'references', 'foundation-compatibility.json') }
   while (argv.length) {
     const flag = argv.shift()
     if (flag === '--registry') result.registry = resolve(flagValue(argv, flag))
@@ -33,11 +33,31 @@ function args(argv) {
     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 if (flag === '--compatibility') result.compatibility = resolve(flagValue(argv, flag))
     else throw new Error(`Unknown option: ${flag}`)
   }
   return result
 }
 
+// Security-advisory watch: query OSV.dev for every pinned npm/PyPI package. Advisories against a
+// pinned version are the highest-value freshness signal — they surface in the weekly report and
+// fail closed for critical sources so a vulnerable pin is never silently kept.
+async function osvAdvisories(source, allowHttpLocalhost) {
+  const detection = source.versionDetection ?? {}
+  const ecosystem = { npm: 'npm', 'npm-suite': 'npm', pypi: 'PyPI' }[detection.type]
+  const version = String(source.pinnedVersion ?? '')
+  if (!ecosystem || !/^\d/.test(version)) return []
+  const packages = detection.type === 'npm-suite' ? detection.packages : [detection.package]
+  const findings = []
+  for (const name of packages) {
+    const response = await safeFetch('https://api.osv.dev/v1/query', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ package: { name, ecosystem }, version }) }, allowHttpLocalhost)
+    if (!response.ok) throw new Error(`OSV HTTP ${response.status} for ${name}`)
+    const data = JSON.parse(new TextDecoder().decode(await readBounded(response)))
+    for (const vuln of data.vulns ?? []) findings.push({ package: name, version, id: vuln.id, summary: vuln.summary ?? null })
+  }
+  return findings
+}
+
 function privateAddress(address) {
   if (address === '::1' || address === '::' || address.startsWith('fc') || address.startsWith('fd') || address.startsWith('fe80:')) return true
   if (!isIP(address)) return true
@@ -240,7 +260,17 @@ export async function refreshEvidence(options) {
   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 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: [], advisories: [], advisoryCheckFailed: [], reviewOverdue: [] }
+  // Baseline-adoption nags: a reviewBy date that passed without a human decision, or a critical
+  // pin lagging a known-newer current version, is how pins rot politely — surface both on every
+  // run (warning, never fail-closed).
+  if (options.compatibility && await pathExists(options.compatibility)) {
+    const compatibility = JSON.parse(await readFile(options.compatibility, 'utf8'))
+    for (const [name, baseline] of Object.entries(compatibility.baselines ?? {})) {
+      if (baseline.reviewBy && Date.parse(`${baseline.reviewBy}T23:59:59Z`) < now.getTime()) report.reviewOverdue.push({ baseline: name, reviewBy: baseline.reviewBy, state: baseline.state })
+    }
+  }
+  report.pinLag = registry.sources.filter(source => source.critical && /^\d/.test(String(source.pinnedVersion ?? '')) && /^\d/.test(String(source.currentVersion ?? '')) && source.pinnedVersion !== source.currentVersion).map(source => ({ id: source.id, pinned: source.pinnedVersion, current: source.currentVersion }))
   const baselineUpdates = new Map()
   for (const source of selected) {
     const prior = cache.sources[source.id]
@@ -261,6 +291,11 @@ export async function refreshEvidence(options) {
         else report.unaffected.push(source.id)
         continue
       }
+      try {
+        for (const advisory of await osvAdvisories(source, options.allowHttpLocalhost)) report.advisories.push(item(source, advisory))
+      } catch (error) {
+        report.advisoryCheckFailed.push(item(source, { error: error.message }))
+      }
       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 —
@@ -316,13 +351,16 @@ export async function refreshEvidence(options) {
   }
   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)
+  const failClosed = [...report.stale, ...report.unavailable, ...report.drift, ...report.versionDrift, ...report.advisories, ...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}` : ''}`)
+  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} advisories=${report.advisories.length}${report.reviewOverdue.length ? ` review-overdue=${report.reviewOverdue.length}` : ''}${report.acceptedBaselines.length ? ` accepted=${report.acceptedBaselines.length}` : ''}`)
+  for (const overdue of report.reviewOverdue) console.error(`warning: baseline ${overdue.baseline} (${overdue.state}) passed its reviewBy ${overdue.reviewBy} — a human adoption decision is overdue`)
+  for (const lag of report.pinLag ?? []) console.error(`warning: critical source ${lag.id} pin ${lag.pinned} lags current ${lag.current} — review adoption or record the deliberate hold`)
+  for (const advisory of report.advisories) console.error(`advisory: ${advisory.package}@${advisory.version} — ${advisory.id}${advisory.summary ? `: ${advisory.summary}` : ''}`)
   if (failClosed) process.exitCode = 1
 }