@vegastack/skills 0.1.0 → 0.3.0

package/skill/{vegastack-arch-guardian → arch-guardian}/references/workflows.md

@@ -4,13 +4,13 @@
 
 Discover confirmed facts before recommending. Ask no more than three material questions at once and branch only when an answer activates a topic:
 
-1. Product objective, users, lifecycle stage, access and tenancy mode.
+1. Product objective, users, lifecycle stage, access, tenancy mode — and the **tier** (prototype / production / enterprise), a deliberate choice the user confirms.
 2. Clients: web, Flutter, public API, connectors or channels.
 3. Agents, automation, ordinary jobs, untrusted execution and external effects.
-4. Data classes, residency, retention, deletion, RPO/RTO and availability/latency objectives.
+4. Data classes, residency, retention, deletion, RPO/RTO and availability/latency objectives (production tier and above).
 5. Hosting/self-hosting, workload/growth, team/on-call/cost, milestone, and deferrable choices.
 
-If facts are unavailable, name bounded assumptions and choose the simplest applicable default. Recommend one capability set and topology. For each enabled capability state ownership, boundary, contract, placement, immediate/deferred decisions, risks, implementation order and qualification evidence. Offer a profile/artifact draft; write only after confirmation.
+If facts are unavailable, name bounded assumptions and choose the simplest applicable default. Recommend one capability set and topology sized by the minimum-viable-architecture principle: every proposed moving service names the trigger that justifies it, and every deferred one names the trigger that would. State immediate and deferred decisions, risks, implementation order, and what evidence would qualify the design at the declared tier. Offer a slim profile draft; write only after confirmation.
 
 ## Brownfield
 
@@ -20,26 +20,29 @@ Separate:
 
 - current observed state;
 - intended state from committed artifacts;
-- target recommendation;
+- target recommendation at the declared tier;
 - immediate security/correctness risks;
 - required migrations and rollback;
 - optional improvements;
-- runtime evidence that is `NOT VERIFIED`.
+- runtime evidence that is not verified.
 
 Prefer incremental migration with compatibility windows and rollback over needless rewrites. Never convert detection heuristics into claims of absence or compliance.
 
+## Reviews
+
+Identify the decision scope, gather evidence (read the relevant files; use the evidence recipes in the [advisory report contract](advisory-report.md)), and produce an advisory report: per-area grades, severity-ranked findings with evidence, questions, and not-verified items. Findings above the project's tier report as that tier's gate, not as defects.
+
 ## Other lifecycle tasks
 
-For questions and explanations, answer directly: the verdict if there is one, the recommendation, and at most one material risk. The full eight-part response contract applies only to design reviews, ADRs, and migration plans — not to questions, explanations, or short follow-ups.
+For questions and explanations, answer directly: the recommendation and at most one material risk. The full response contract applies only to design reviews, ADRs, and migration plans.
 
 - **Explanation:** answer the decision directly; load only references needed to explain it.
-- **Review:** identify decision scope, run applicable checks, and prioritize actionable findings.
-- **ADR:** distinguish a foundation change from project accepted risk; record exact control/path scope.
-- **Threat model:** model only enabled/exposed surfaces and their trust boundaries.
-- **Deployment:** compare declared production target with deployables, data, secrets, SLO/recovery and rollback.
-- **Source drift:** refresh affected entries only; qualification state changes only through review.
+- **ADR:** a decision record, not a waiver — capture owner, decision, alternatives, risks, and revisit trigger.
+- **Threat model:** model only enabled/exposed surfaces and their trust boundaries, at the tier's depth.
+- **Deployment:** compare declared hosting with deployables, data, secrets, recovery and rollback.
+- **Source drift:** refresh affected entries only; recommendations change only through review.
 - **Migration/removal:** distinguish current/target state, preserve compatibility, and clean durable data, credentials, queues and contracts.
 
 ## Decision horizons
 
-Sequence work as: irreversible security/data/identity boundaries; contracts and durable ownership; deployable placement and recovery; delivery scaffolding; measured optimization. Every phase names owner, verification, rollback and any ADR action.
+Sequence work as: irreversible security/data/identity boundaries; contracts and durable ownership; deployable placement and recovery; delivery scaffolding; measured optimization. Every phase names owner, verification, rollback and any decision record to update.

package/skill/{vegastack-arch-guardian → arch-guardian}/refresh/REFRESH.md

@@ -1,4 +1,4 @@
-# Refresh contract — vegastack-arch-guardian
+# Refresh contract — arch-guardian
 
 Instructions for the scheduled refresh agent (and any human running a manual refresh). This file, together with `sources.json`, is the complete freshness contract for this skill.
 
@@ -14,12 +14,14 @@ Instructions for the scheduled refresh agent (and any human running a manual ref
 
 1. **Deterministic pass first** (no LLM judgment):
    `node scripts/refresh-evidence.mjs --registry refresh/sources.json`
-   drift/version-drift/stale/unavailable results are the work-list. Exit 1 with a critical entry means fail-closed: the run must not be silently skipped.
+   drift/version-drift/stale/unavailable results are the work-list. Exit 1 with a critical entry means fail-closed: the run must not be silently skipped. The same pass also:
+   - queries OSV.dev for every pinned npm/PyPI package (`advisories` in the report; an advisory against a critical source's pin fails closed — the remediation is a human pin-bump decision, never silence);
+   - warns when a `reviewBy` date in `references/foundation-compatibility.json` has passed (`reviewOverdue`) — the baseline-adoption decision is overdue, and the warning repeats every run until a human makes it.
 2. **Accept verified changes** in the same code path:
    `node scripts/refresh-evidence.mjs --registry refresh/sources.json --accept-baselines`
    This writes registry, cache, and drift report together — never hand-edit checksums, versions, or timestamps; they must always come from a run.
 3. **Semantic verification** only for sources the deterministic pass flagged: read the changed source (WebFetch the registry URLs), decide whether any `<!-- source: X -->` marked sentence or compatibility pin is now wrong, and propose the minimal edit.
-4. **One PR per refresh**, branch `refresh/<date>`, force-updating the standing refresh branch if last week's PR is unmerged (never stack duplicate PRs). PR body lists: each changed source, old→new version/checksum, links to the evidence, and which marked sentences changed and why.
+4. **One standing refresh PR**, branch `refresh/weekly`, force-updated on every run (never stacked duplicates; the weekly workflow .github/workflows/refresh.yml maintains it). PR body lists: each changed source, old→new version/checksum, links to the evidence, and which marked sentences changed and why.
 5. Changes to durable rules, scripts, SKILL.md, assets, or tests are out of scope for a refresh PR — CI enforces this (refresh-guard workflow).
 
 ## Cadence and thresholds
@@ -31,6 +33,11 @@ Weekly scheduled run. Every `thresholdDays` in `sources.json` is ≥ 14 (2× cad
 - A pinned package/spec version changed (npm/pypi detection) → update `currentVersion`; if the supported baseline should move, that is a **separate human decision**, flagged in the PR body, never auto-applied to `foundation-compatibility.json` families.
 - A doc page's text-scope checksum changed → read the page; if the mechanism a marked sentence names changed, propose the sentence edit; if it is editorial churn, accept the baseline silently. Known per-request-churn sources (Google properties: `FCM-DOCS`, `GOOGLE-MODELS`) drift on nearly every fetch — their checksum drift alone is never a semantic signal; rely on their version/manual review instead.
 - A critical source is unavailable or a redirect leaves the approved host set → investigate immediately; host changes require a deliberate `approvedHosts` update in `scripts/refresh-evidence.mjs` (out of refresh-PR scope — open an issue).
+- An OSV advisory against a pinned package → propose the pin bump (with its qualification implications) in the PR body; never drop the advisory from the report.
+
+## Research index
+
+Registry entries carry an optional `llms` URL (the vendor's published `llms.txt`) alongside `docsIndex`. Agents answering questions that need current detail beyond a pinned claim should fetch the source's `llms` or `docsIndex` URL (or use an available docs MCP) — the registry doubles as the live research index, not just freshness metadata.
 
 ## Never
 

package/skill/{vegastack-arch-guardian → arch-guardian}/refresh/sources.json

@@ -22,8 +22,8 @@
       "service": "EVE",
       "kind": "pinned-source-package",
       "pinnedVersion": "0.29.5",
-      "currentVersion": "0.31.2",
-      "versionCheckedAt": "2026-08-07T18:47:48.335Z",
+      "currentVersion": "0.31.3",
+      "versionCheckedAt": "2026-08-08T07:53:01.687Z",
       "commit": "8988139097d1e1a1f1aca9b2828e63408848fccf",
       "stability": "beta-protocol-critical",
       "thresholdDays": 14,
@@ -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",
@@ -639,7 +646,7 @@
       "service": "Turborepo",
       "kind": "official-docs",
       "pinnedVersion": "2.5.6",
-      "currentVersion": "2.10.8",
+      "currentVersion": "2.10.9",
       "stability": "tooling",
       "thresholdDays": 30,
       "critical": false,
@@ -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",
@@ -666,7 +674,7 @@
         "rule:PKG-002",
         "ref:topology-monorepo"
       ],
-      "versionCheckedAt": "2026-08-07T18:47:48.335Z"
+      "versionCheckedAt": "2026-08-08T07:53:01.687Z"
     },
     {
       "id": "FLUTTER-DOCS",
@@ -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-07T18:47:48.335Z",
-      "checksum": "a8e45e4fda04b32279f1a82bd0afa7380b70f738cc1b5ee42ab178945d7dd1fe",
+      "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"
@@ -1047,7 +1058,7 @@
       "service": "AI SDK",
       "kind": "official-docs-package",
       "pinnedVersion": "7.x",
-      "currentVersion": "7.0.57",
+      "currentVersion": "7.0.58",
       "stability": "model-library",
       "thresholdDays": 30,
       "critical": false,
@@ -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",
@@ -1075,7 +1087,7 @@
         "rule:MODEL-001",
         "ref:models-observability"
       ],
-      "versionCheckedAt": "2026-08-07T18:47:48.335Z"
+      "versionCheckedAt": "2026-08-08T07:53:01.687Z"
     },
     {
       "id": "ANTHROPIC-MODELS",
@@ -1152,8 +1164,8 @@
         "ref:model-lifecycle",
         "ref:models-observability"
       ],
-      "checksum": "379866ba1eef7fa6ed14b14f7961fb3f58989e02dc1e54d12c4a8293d87667fd",
-      "retrievedAt": "2026-08-07T19:12:27.794Z"
+      "checksum": "5f2224358c1f3f47ba6cdd5e46b2d695a2c8bfcad93faedcab549290fcada1e6",
+      "retrievedAt": "2026-08-08T07:53:01.687Z"
     }
   ]
 }

package/skill/{vegastack-arch-guardian → 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/{vegastack-arch-guardian → 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/{vegastack-arch-guardian → 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(['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'])
+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 —
@@ -309,17 +344,23 @@ export async function refreshEvidence(options) {
       Object.assign(source, update)
       report.acceptedBaselines.push({ id: source.id, ...update })
     }
+    // A manual-review flag raised earlier in this same run is satisfied by the acceptance that
+    // just refreshed the source's retrievedAt — it must not fail-close the run that fixed it.
+    for (const entry of report.manualVersionReview) if (baselineUpdates.get(entry.id)?.retrievedAt) { entry.due = false; entry.ageDays = 0 }
     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)
+  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
 }