@vegastack/skills 0.1.0

package/skill/vegastack-arch-guardian/references/foundation-compatibility.json

@@ -0,0 +1,44 @@
+{
+  "schemaVersion": 1,
+  "foundationVersion": "0.3.0",
+  "baselines": {
+    "vs-2026-08-07": {
+      "state": "supported",
+      "reviewBy": "2026-11-07",
+      "families": {
+        "web": { "next": "16.3.0", "node": "24.18.0", "bun": "1.3.14" },
+        "cloudflare-opennext": { "openNext": "1.20.2" },
+        "agents": { "eve": "0.29.5", "workflowWorldContract": "5.0.0-beta.23", "workflowLocal": "5.0.0-beta.32", "workflowPostgres": "5.0.0-beta.30", "node": "24.18.0" },
+        "jobs": { "pgBoss": "12.27.0", "postgres": "17.10" },
+        "identity": { "betterAuth": "1.6.26" },
+        "sandbox-cloudflare": { "cloudflareSandbox": "0.12.4" }
+      }
+    },
+    "candidate": {
+      "state": "candidate",
+      "qualificationRequired": true,
+      "reviewBy": "2026-09-07",
+      "families": {},
+      "observedVersions": { "eve": "0.31.2", "workflowPostgres": "5.0.0-beta.32", "postgres": "18.4" },
+      "qualificationBlockers": ["complete compatible Workflow protocol family not established", "migration/replay/rollback qualification not run", "PostgreSQL 18 major not qualified against RLS/pgvector/pg-boss workloads"]
+    },
+    "vs-2026-05-01": {
+      "state": "deprecated",
+      "reviewBy": "2026-09-01",
+      "removalBy": "2026-12-01",
+      "families": {}
+    }
+  },
+  "policy": {
+    "exactProjectVersions": true,
+    "atomicFamilies": ["agents"],
+    "lagOrAdvanceRequiresProjectAdr": true
+  },
+  "sourceDrift": {
+    "observedAt": "2026-08-08T00:00:00.000Z",
+    "status": "qualification-required",
+    "criticalSources": ["EVE-PINNED", "WORKFLOW-PG", "PGBOSS-1227", "NEXT-1630", "OPENNEXT-1202", "CF-WORKERS", "CF-SANDBOX", "HYPERDRIVE", "AI-GATEWAY", "MODAL-SANDBOX", "BETTERAUTH-OAUTH", "BETTERAUTH-ORG", "BETTERAUTH-SESSIONS", "BETTERAUTH-SSO", "BETTERAUTH-SCIM", "BETTERAUTH-APIKEY", "BETTERAUTH-SECURITY", "APP-AUTH", "POSTGRES-DOCS", "OPENBAO-DOCS", "MCP-SPEC"],
+    "registry": "refresh/sources.json",
+    "disposition": "criticalSources mirrors every critical:true entry in refresh/sources.json (kept in sync by refresh runs); keep the supported tuple pinned; review affected rules and qualify the candidate before changing the supported baseline. Existing project ADRs remain active until their own review trigger."
+  }
+}

package/skill/vegastack-arch-guardian/references/golden-patterns.md

@@ -0,0 +1,43 @@
+# Golden implementation patterns
+
+Use these as concise boundary shapes, not copy-paste frameworks.
+
+## Protected request and transaction-local RLS
+
+Authenticate → resolve current membership server-side → authorize typed action → begin transaction → `SET LOCAL`/`set_config(..., true)` workspace, subject and support context → query with composite tenant key → append audit correlation → commit. Request roles are non-owner and never `BYPASSRLS`.
+
+## AgentRun and transactional admission
+
+In one PostgreSQL transaction, create `AgentRun` plus one pg-boss admission job keyed by `(workspace_id, admission_key)`. Use an outbox only across a real database/transaction boundary. The trusted EVE projection, not the admission worker, advances terminal state.
+
+## Lost acknowledgement recovery
+
+On uncertain EVE start acknowledgement, look up the session by the deterministic admission key before retry. Resume the same logical session; never create a second run.
+
+## Effect fence and reconciliation
+
+Persist a tenant-scoped effect key and intended operation before a retried external effect. Reuse the key, record provider outcome, and reconcile unknown results before retrying.
+
+## Capability envelope and credential broker
+
+Issue a short-lived capability bound to audience, workspace, resource, action, data/risk class and approval. A trusted broker validates it, reconstructs an allowlisted request and injects a credential; agents and sandboxes never receive ambient or refresh credentials.
+
+## Safe connector HTTP and redirects
+
+Bound method, ports, path, body, response and time. Resolve and validate DNS against the actual connection; reject private, loopback, link-local, metadata and multicast targets at every redirect; strip cross-origin credentials and re-authorize each hop.
+
+## Resumable SSE
+
+Emit tenant/run identity, monotonic cursor, event and schema version, timestamp and trace correlation. Reconnect with last acknowledged cursor; replay authorized retained events or return a snapshot/terminal result. Bound buffers and expose truncation.
+
+## Deterministic contracts
+
+Treat bounded Zod schemas as editable wire source. Generate OpenAPI, Flutter/public clients and snapshots with pinned tools, canonical ordering and digests. CI regenerates and fails on drift.
+
+## Deletion propagation
+
+Create a durable deletion intent, enumerate PostgreSQL, objects, indexes/vectors, caches, telemetry and connector copies, track each outcome, retry safely, honor scoped legal holds and reconcile to completion.
+
+## Support-session authorization
+
+Create visible, reason/ticket-bound, expiring and revocable support elevation. Authorize each action through normal typed policy and tenant RLS; append immutable audit. Never impersonate a user or grant `BYPASSRLS`.

package/skill/vegastack-arch-guardian/references/profile-governance.md

@@ -0,0 +1,54 @@
+# Profile and governance
+
+The v3 profile declares project facts without assuming a full-stack product. `capabilities` is authoritative intent; repository detection is evidence for drift, not a reason to silently enable anything.
+
+## Capability ownership
+
+- `owned`: the project owns source, deployment, operations and migration. Enabled owned capabilities declare exact versions, placement and source roots.
+- `shared-managed`: another VegaStack owner runs the capability for this project.
+- `external-managed`: a third party runs it behind a project-approved contract.
+- `not-applicable`: use only for disabled capabilities.
+
+Enabled shared/external capabilities declare owner/service, contract name/version, tenant/security boundary, identity/audience, data/residency, SLO/recovery dependency, incident ownership, compatibility and migration/exit behavior. They do not require provider source roots in the consumer repository.
+
+Owned durable capabilities declare concrete owners in `controls`: agents name `workflowDatabaseOwner` and `agentRunOwner`; jobs name `databaseOwner`; owned knowledge names `postgresOwner` and, when `binaryObjects` is true, `objectStorageOwner`; notifications name `durableIntentOwner`. Credential-bearing connectors/model routing set `credentialBearing: true`, and SCIM activates production secret custody. These are confirmed project facts, never generated placeholders.
+
+Never invent owner, SLO, retention, residency, compliance or version values. Missing material facts remain validation errors or `NOT VERIFIED` evidence.
+
+## Capability activation
+
+Apply rules only when activated by declared intent or observed drift. Key implications:
+
+- Flutter requires delegated OAuth/OIDC code with S256 PKCE and generated REST/OpenAPI client consumption.
+- Agents require qualified EVE/Postgres World plus AgentRun.
+- Owned agent admission requires pg-boss; shared admission requires an explicit qualified contract.
+- Untrusted execution requires a sandbox and trusted capability broker.
+- SCIM requires organization mapping and complete deprovisioning.
+- Cloudflare/OpenNext plus owned agents/jobs requires external long-running Node/OCI placement.
+- Removing a capability requires a cleanup/migration plan for durable data, credentials, queues and contracts.
+- Production secrets activate OpenBao unless an explicit shared/external secrets contract is declared.
+
+## Exceptions
+
+Every project rule is waivable by the project owner. A valid exception declares an exact single rule, exact repository-relative evidence paths, project owner, rationale/decision, risks, compensating controls, verification, rollback/migration, review date or event, and acknowledgement of foundation deviation. `controls` is optional: an exception that omits it covers all controls under its single rule; one that declares control IDs suppresses only the controls it lists. Its contained ADR repeats the identity and decision.
+
+Static exceptions match only when rule and exact evidence path match and, when `controls` is declared, the control ID also matches. Wildcards and directory-prefix suppression are forbidden. An exception that lists controls never suppresses a finding for a control it does not list, and no exception covers a second rule. Manual exceptions declare `verificationType: manual-qualification` and remain visibly accepted risk.
+
+Outcome semantics:
+
+| Outcome | Meaning | CI |
+|---|---|---|
+| `PASS` | recommendation satisfied | pass |
+| `FAIL` | violation or invalid/expired/mismatched exception | fail |
+| `EXCEPTED` | valid active project-owner accepted risk; recommendation remains unmet | pass |
+| `NOT VERIFIED` | environment behavior not reproduced; reason/risk/owner/next action required | configurable warning |
+
+The guardian may still state `GUARDIAN VERDICT: REJECT` when an accepted risk is unsafe. Foundation evolution changes the recommended baseline; project exceptions remain distinguishable and do not silently expire on source drift.
+
+## Governance operations
+
+- Evidence labels are optional; they are reserved for review and drift reports and never affect exception matching.
+- Drift PRs from the automated source refresh are reviewed by whoever merges them; drift policy has no per-topic owners.
+- Source staleness thresholds are a minimum of 14 days, aligned to the weekly automated refresh; shorter thresholds only produce false staleness between refreshes.
+- Profiles pin the foundation version (currently `0.3.0`); it is decoupled from the installer npm package version, so installer upgrades never change a project's pinned foundation.
+- `DUR-007`-style full qualification matrices are required before the first paying tenant, not before every merge; interim merges record `NOT VERIFIED` with reason, owner, and next action.

package/skill/vegastack-arch-guardian/references/rule-model.json

@@ -0,0 +1,36 @@
+{
+  "schemaVersion": 1,
+  "defaults": { "classification": "invariant", "waiver": "project-owner-adr", "authority": "canonical prose in references/architecture" },
+  "groups": [
+    { "rules": ["FOUND-001", "FOUND-002", "FOUND-003", "FOUND-004"], "activation": "profile, governance, or any guardian output", "verification": "structural, semantic, output review", "rationale": "Keep project facts, accepted risk, and capability applicability honest." },
+    { "rules": ["API-001", "API-002", "API-003", "API-004", "WEB-001"], "activation": "web control plane or public/generated API enabled or observed", "verification": "static, generated-contract, runtime", "rationale": "Keep one portable control-plane contract and safe request boundary." },
+    { "rules": ["MOB-001", "MOB-002", "MOB-003", "MOB-004"], "activation": "Flutter enabled or observed", "verification": "semantic, generated-contract, mobile runtime", "rationale": "Keep delegated mobile identity, wire contracts, local secrets, push, and links safe." },
+    { "rules": ["AUTH-001", "AUTH-002", "AUTH-003", "AUTH-004", "AUTH-005", "AUTH-006", "AUTH-007"], "activation": "the corresponding authenticated, delegated, service, enterprise, or support access exists", "verification": "static, semantic, identity integration", "rationale": "Bind identity and authorization to current durable project state." },
+    { "rules": ["TEN-001", "TEN-002", "TEN-003", "TEN-004"], "activation": "shared-schema multi-tenancy enabled or tenant context observed", "verification": "SQL static analysis and negative runtime tests", "rationale": "Prevent cross-tenant access through keys, policies, roles, and privileged paths." },
+    { "rules": ["AGENT-001", "AGENT-002", "AGENT-003", "AGENT-004"], "activation": "agent authoring/publication enabled or observed", "verification": "compiler determinism, schema, eval and publication tests", "rationale": "Make published agent behavior immutable, pinned and reviewable." },
+    { "rules": ["DUR-001", "DUR-002", "DUR-003", "DUR-004", "DUR-005", "DUR-006", "DUR-007", "DUR-008", "DUR-009"], "activation": "agents, agent admission, jobs, retried effects, or shared tenant Workflow World as specified", "verification": "static, semantic, crash/replay/reconciliation", "rationale": "Give each durable state class one owner and qualify recovery, tenancy, and engine exit safely." },
+    { "rules": ["CONN-001", "CONN-002", "CONN-003", "CONN-004", "CONN-005"], "activation": "connector, MCP or webhook enabled or observed", "verification": "static, SSRF/replay/credential integration", "rationale": "Constrain external capabilities, identity and side effects at the trust boundary." },
+    { "rules": ["SBX-001", "SBX-002", "SBX-003", "SBX-004", "SBX-005"], "activation": "untrusted execution or sandbox enabled or observed", "verification": "semantic and live isolation/egress/cleanup tests", "rationale": "Keep untrusted execution disposable, credential-free and policy-brokered." },
+    { "rules": ["DATA-001", "DATA-002", "DATA-003", "DATA-004", "DATA-005"], "activation": "corresponding business, knowledge, memory, object, or lifecycle data exists", "verification": "schema, authorization, deletion, object security and recovery tests", "rationale": "Keep authoritative data, derived state and lifecycle ownership explicit." },
+    { "rules": ["RT-001", "RT-002", "RT-003", "RT-004", "RT-005", "RT-006"], "activation": "corresponding realtime, channel, or notification capability exists", "verification": "protocol, ingress, reconnect, dedupe and delivery tests", "rationale": "Separate ephemeral transport from durable event and notification ownership." },
+    { "rules": ["MODEL-001", "MODEL-002", "MODEL-003"], "activation": "model routing or BYOK enabled or observed", "verification": "route policy, credential and fallback integration", "rationale": "Preserve tenant, region, retention and key-source policy across model routes." },
+    { "rules": ["OBS-001", "OBS-002", "OBS-003"], "activation": "telemetry or audit surface exists", "verification": "static redaction and telemetry/audit integration", "rationale": "Provide useful evidence without leaking sensitive content." },
+    { "rules": ["SEC-001", "SEC-002", "SEC-003", "SEC-004", "SEC-005"], "activation": "the corresponding exposed capability, secret, authorization, build or abuse surface exists", "verification": "threat model, static, security integration", "rationale": "Enforce security in typed/runtime boundaries rather than prompts or assumptions." },
+    { "rules": ["RUN-001", "RUN-002", "RUN-003", "RUN-004"], "activation": "corresponding owned deployable/provider boundary exists", "verification": "source graph, bundle and runtime qualification", "rationale": "Keep runtimes inside supported ownership and trust boundaries." },
+    { "rules": ["PKG-001", "PKG-002", "PKG-003", "PKG-004"], "activation": "package graph, generated contract, version family, or production deployable exists", "verification": "graph, deterministic generation, compatibility/replay", "rationale": "Keep packages directed, production graphs verified, and protocol families atomically qualified." },
+    { "rules": ["HOST-001", "HOST-002", "HOST-003", "HOST-004"], "activation": "production deployable uses the corresponding hosting profile", "verification": "semantic, bundle and deployment qualification", "rationale": "Make runtime placement and provider limitations explicit." },
+    { "rules": ["REL-001", "REL-002", "REL-003", "REL-004"], "activation": "applicable production objective, durable data, region/cell, or incident surface exists", "verification": "declared objective and live recovery/incident drill", "rationale": "Tie architecture to measured service and recovery behavior." },
+    { "rules": ["DEL-001", "DEL-002", "DEL-003", "DEL-004", "DEL-005", "DEL-006"], "activation": "corresponding enabled capability, migration, release, source decision, or environment test exists", "verification": "CI, migration, release and evidence checks", "rationale": "Deliver changes compatibly and report only evidence actually reproduced." },
+    { "rules": ["EVAL-001", "EVAL-002", "EVAL-003", "EVAL-004"], "activation": "agents, prompts, or model-backed behavior shipped to users", "verification": "eval regression, dataset versioning, sampling policy review", "rationale": "Gate agent, prompt, and model changes on reproduced evaluation evidence." },
+    { "rules": ["MLIFE-001", "MLIFE-002", "MLIFE-003", "MLIFE-004"], "activation": "external model providers enabled or observed", "verification": "route policy, deprecation tracking, canary and pressure qualification", "rationale": "Keep model choice explicit and migratable and behavior stable under provider change and load." },
+    { "rules": ["COST-001", "COST-002", "COST-003", "COST-004"], "activation": "metered AI, sandbox, or knowledge-processing resources exist", "verification": "attribution, budget, and cost-regression checks", "rationale": "Treat AI spend as an owned architectural resource with attribution, budgets, and deploy gates." },
+    { "rules": ["PII-001", "PII-002", "PII-003", "PII-004"], "activation": "personal data, knowledge ingestion, external model calls, or public AI output exists", "verification": "redaction, moderation, and injection-mitigation review", "rationale": "Keep personal data and untrusted content controlled across AI trust boundaries." }
+  ],
+  "overrides": [
+    { "rule": "RT-002", "classification": "preferred-default", "permittedOption": "WebSockets for an explicit bidirectional collaboration/presence requirement; durable-state and default-transport misuse is enforced under DUR-001 and RT-001" },
+    { "rule": "HOST-002", "classification": "preferred-default", "permittedOption": "A different qualified self-host topology through project ADR" },
+    { "rule": "DATA-002", "classification": "preferred-default", "permittedOption": "A qualified external/shared knowledge service through declared ownership contract" },
+    { "rule": "MLIFE-003", "classification": "preferred-default", "permittedOption": "Direct rollout for a low-risk change with eval pass and one-step rollback" },
+    { "rule": "COST-003", "classification": "preferred-default", "permittedOption": "No prompt/context caching until a measured benefit exists" }
+  ]
+}

package/skill/vegastack-arch-guardian/references/workflows.md

@@ -0,0 +1,45 @@
+# Adaptive workflows
+
+## Greenfield
+
+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.
+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.
+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.
+
+## Brownfield
+
+Before asking, inspect repository instructions, manifests and locks, deployables, package graph, schemas/migrations, identity, APIs/generated clients, jobs/workflows, infra/deployment, ADRs, telemetry and runbooks. Run `profile-tool.mjs inspect` for an observed read-only draft.
+
+Separate:
+
+- current observed state;
+- intended state from committed artifacts;
+- target recommendation;
+- immediate security/correctness risks;
+- required migrations and rollback;
+- optional improvements;
+- 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.
+
+## 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.
+
+- **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.
+- **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.

package/skill/vegastack-arch-guardian/refresh/REFRESH.md

@@ -0,0 +1,40 @@
+# Refresh contract — vegastack-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.
+
+## What this skill claims
+
+- **Durable rules** (`references/architecture/*.md`, `references/*.md|json`): versionless principles. The refresh agent NEVER edits these. If a source change invalidates a durable rule, open an issue titled `drift: <rule-id>` quoting the evidence — do not edit.
+- **Mechanism-coupled claims**: sentences marked `<!-- source: SOURCE-ID -->` inside references. Durable intent expressed through vendor-named mechanisms (e.g. Better Auth option names, sandbox egress API, MCP negotiation). The agent may propose edits to these marked sentences ONLY, in the same PR as the registry update that evidences the change.
+- **Volatile layer** (the only files the agent edits freely):
+  - `refresh/sources.json` — the source registry and publish-time staleness snapshot (checksums, versions, retrieval times).
+  - `references/foundation-compatibility.json` — pinned baselines and the criticalSources mirror.
+
+## How to refresh
+
+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.
+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.
+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
+
+Weekly scheduled run. Every `thresholdDays` in `sources.json` is ≥ 14 (2× cadence) so one missed run never breaches a threshold. Sources that would genuinely need faster tracking get a daily deterministic-only version check, not a lower threshold.
+
+## What counts as drift worth a PR
+
+- 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).
+
+## Never
+
+- Never edit rule IDs, MUST/SHOULD wording, or unmarked sentences.
+- Never expire, edit, or reference project ADRs — drift requests review; it never silently expires an ADR.
+- Never hand-write checksum/version/timestamp values.
+- Never archive third-party documentation bodies in this repo (claim metadata, URLs, hashes, and concise excerpts only).