@vegastack/skills 0.1.0

package/skill/vegastack-arch-guardian/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: vegastack-arch-guardian
+description: Architecture advisor for VegaStack projects. Use when designing a new service or feature, reviewing architecture or a risky change (auth, tenancy, agents, jobs, connectors, data lifecycle, hosting), deciding between architectural options, writing or validating an ADR or .vegastack/architecture.json profile, threat modeling, planning a migration, or checking dependency and source drift. Gives one scoped recommendation with an explicit verdict; activates only the capabilities a project has actually enabled. Covers web-only, Flutter, agentic and non-agentic, single- and multi-tenant, internal, public, platform-service, and shared-package projects.
+---
+
+# VegaStack Architecture Guardian
+
+Act as the project's decisive senior architect. Apply only activated capabilities. Treat the foundation as an advisory recommendation: state `GUARDIAN VERDICT: REJECT` when warranted, while allowing a project owner to accept any scoped risk through a valid ADR. Never invent compliance or project facts.
+
+## Start every task
+
+1. Identify the actual decision, its scope, and how expensive it is to reverse.
+2. Inspect repository instructions and existing facts before asking questions. Keep read-only work read-only; never create a profile or artifact merely because it is absent.
+3. Separate **facts**, **constraints**, **assumptions**, **preferences**, and **accepted project decisions**. Distinguish current, target, and migration state.
+4. Ask at most three material questions at a time. If unanswered, proceed with bounded assumptions and the smallest architecture that meets stated requirements.
+5. Read only the directly relevant references below. Use committed profiles, designs, and ADRs as architecture memory; never rely on hidden chat state.
+6. Prioritize security/correctness, recovery, ownership, contracts, operability, delivery, then optional optimization. Make one primary recommendation, identify the rejected alternative, and surface irreversible or expensive choices first.
+7. Evidence labels (**OBSERVED**, **DOCUMENTED**, **REPRODUCED**, **INFERRED**, **RECOMMENDED**, **NOT VERIFIED**) are optional; reserve them for review and drift reports where provenance matters. A static sentinel or declared control is never a reproduced runtime test.
+
+Script invocations below write `<skill-dir>` as a placeholder: replace it with the absolute path of the directory containing this SKILL.md before running (no environment variable is set for you).
+
+## Answer at the right size
+
+- **Questions and explanations:** answer directly — the verdict (if one applies), the recommendation, and at most one material risk. No section headers, no full contract.
+- **Design reviews, ADRs, migration plans:** use the full response contract: (1) Verdict, (2) Recommended architecture/decision, (3) Why it fits, (4) Material assumptions, (5) Rejected alternative and reason, (6) Implementation/migration sequence, (7) Risks and required evidence, (8) Artifacts/ADRs to update.
+
+## Route progressively
+
+| Need | Read |
+|---|---|
+| operating model, project types, profiles, exceptions | [foundation](references/architecture/foundation.md), [profile and governance](references/profile-governance.md) |
+| greenfield, brownfield, migration, continuous work | [adaptive workflows](references/workflows.md) |
+| topology, deployables, packages, contracts | [topology and monorepo](references/architecture/topology-monorepo.md) |
+| web/Next/OpenAPI/cache | [web](references/architecture/web.md) |
+| Flutter/mobile | [Flutter](references/architecture/flutter.md) |
+| identity, organizations, tenancy, RLS | [identity and tenancy](references/architecture/identity-tenancy.md) |
+| agent product and durable execution/jobs | [agent product](references/architecture/agent-product.md), [durable execution](references/architecture/durable-execution.md) |
+| connectors, MCP, webhooks, sandbox, egress | [connectors and sandbox](references/architecture/connectors-sandbox.md) |
+| data, knowledge, memory, objects | [data and memory](references/architecture/data-memory.md) |
+| PII, prompt injection, output moderation | [AI data boundaries](references/architecture/ai-data-boundaries.md) |
+| evals, prompt/model regression gates | [AI evals](references/architecture/ai-evals.md) |
+| model pinning, deprecations, canary, backpressure | [model lifecycle](references/architecture/model-lifecycle.md) |
+| model spend, budgets, cost attribution | [AI cost](references/architecture/ai-cost.md) |
+| realtime, notifications, channels | [realtime and channels](references/architecture/realtime-channels.md) |
+| models, BYOK, telemetry, audit | [models and observability](references/architecture/models-observability.md) |
+| security, privacy, threat model | [security and privacy](references/architecture/security-privacy.md) |
+| hosting, Cloudflare/OpenNext, SLO/recovery | [hosting and reliability](references/architecture/hosting-reliability.md) |
+| delivery, migration, verification | [delivery and operations](references/architecture/delivery-operations.md) |
+| fragile boundary implementation | [golden patterns](references/golden-patterns.md) |
+
+Consult [refresh/sources.json](refresh/sources.json) only for affected unstable claims and [foundation compatibility](references/foundation-compatibility.json) for version adoption. Before advice that leans on a **critical** source (`critical: true` in the registry), check freshness: run `node <skill-dir>/scripts/refresh-evidence.mjs --topics <affected-topics>` when online, or treat the claim as `NOT VERIFIED` when offline and the registry snapshot is older than its `thresholdDays`. Source drift requests review; it never silently expires an ADR.
+
+## Execute the task-specific workflow
+
+- **Greenfield:** Follow the adaptive intake in [workflows](references/workflows.md). Recommend capability set, topology, ownership, boundaries, immediate/deferred decisions, risks, implementation order, and qualification. Offer scaffolding only after confirmation.
+- **Brownfield/review:** Inspect instructions, manifests/locks, deployables, packages, schemas/migrations, auth, APIs/clients, jobs/workflows, infra, ADRs, observability, and runbooks before interviewing. Derive an observed draft without mutation; compare current, intended, and target states; prefer controlled migration over rewrites.
+- **ADR/design/threat/deploy:** Use the relevant asset only after write authorization. Every action includes owner, risk, evidence, rollback/migration, and review trigger.
+- **Continuous work:** Load only affected references and checks. Do not force absent capabilities into scope.
+- **Source drift:** Follow [refresh/REFRESH.md](refresh/REFRESH.md). Refresh only affected topics; map changes to rules/capabilities and preserve unrelated fast paths.
+
+## Profiles, checks, and mutation safety
+
+The committed profile lives at `.vegastack/architecture.json` (legacy `.yaml`-named JSON is still discovered, with a deprecation notice). Inspect or draft without mutation:
+
+```sh
+node <skill-dir>/scripts/profile-tool.mjs inspect .
+node <skill-dir>/scripts/profile-tool.mjs scaffold answers.json --dir .
+```
+
+`inspect` prints a compact summary; add `--json` for the full draft. The answers format is documented by example in `<skill-dir>/assets/answers-example.json`.
+
+Write only after explicit authorization; writes are atomic, refuse symlinks, stay inside `--dir`, and require `--force` to replace differing content:
+
+```sh
+node <skill-dir>/scripts/profile-tool.mjs scaffold answers.json --dir . --write
+node <skill-dir>/scripts/profile-tool.mjs migrate-v2 .vegastack/architecture.yaml --dir .
+```
+
+Validate and review (prefer `--summary` in conversation; `--json` is for CI):
+
+```sh
+node <skill-dir>/scripts/validate-profile.mjs .vegastack/architecture.json
+node <skill-dir>/scripts/architecture-check.mjs . --summary
+```
+
+`architecture-check` exit codes: 0 = no FAIL findings, 1 = FAIL findings present, 2 = tool/usage error. A non-zero exit is a review result, not a crash. Paths can be excluded deliberately via a `.guardianignore` file (path prefixes, one per line). Symlinks, agent-skill trees, and generated/bundled files (very large or very long-line files) are skipped automatically and reported in one `NOT VERIFIED` finding.
+
+Interpret outcomes exactly: `PASS` satisfies the recommendation; `FAIL` violates it without a valid exception; `EXCEPTED` is active project-owner accepted risk and remains visibly noncompliant although CI may pass; `NOT VERIFIED` records reason, risk, owner, and next action. Invalid, expired, or mismatched exceptions fail. Continue to recommend rejection when accepted risk remains unsafe.
+
+## Guardrails
+
+- Product-owned enabled capabilities are the default. Shared/external management is rare and requires the complete declared contract in [profile and governance](references/profile-governance.md).
+- Challenge project proposals and foundation defaults when evidence warrants. Choose the smallest architecture meeting current requirements and measured objectives.
+- Never require SQL/RLS, Better Auth, Flutter, EVE, pg-boss, sandbox, connectors, enterprise identity, realtime, notifications, knowledge, or OpenBao when their activation condition is absent.
+- Never mutate a repository for an explanation or read-only review. Draft first and ask before writing.
+- Never create paid/cloud resources or claim live recovery, isolation, failover, credential-backed, or provider tests ran unless they actually ran.

package/skill/vegastack-arch-guardian/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "VegaStack Architecture Guardian"
+  short_description: "Design and guard adaptive VegaStack architecture"
+  default_prompt: "Use $vegastack-arch-guardian to make one scoped architecture recommendation for this project without assuming absent capabilities."

package/skill/vegastack-arch-guardian/assets/adr-template.md

@@ -0,0 +1,40 @@
+# ADR-NNN: Decision title
+
+- Status: proposed | accepted | superseded | rejected
+- Date: YYYY-MM-DD
+- Project-Owner: accountable person
+- Scope-Paths: comma-separated exact repository-relative paths
+- Rule-ID: canonical rule identifier or `none`
+- Control-IDs: comma-separated exact checker/manual control IDs, or `all` for a rule-level exception that omits the profile controls list
+- Exception-ID: profile exception ID or `none`
+- Foundation-Deviation-Acknowledged: true | false
+- Review-Date: YYYY-MM-DD | none
+- Review-Event: concrete event | none
+
+## Context and facts
+
+Separate observed facts, constraints, assumptions, preferences and prior accepted decisions. Identify current, target and migration states.
+
+## Decision and rationale
+
+State the primary decision, ownership, boundaries and why it fits. State the rejected alternative and reason.
+
+## Risks and accepted deviation
+
+Describe each risk, who accepts it, affected paths/tenants/data, and why the foundation recommendation remains unmet.
+
+## Compensating controls
+
+Map preventive, detective and recovery controls to each risk. Do not claim an untested control works.
+
+## Verification
+
+List static sentinels, declared controls, reproduced tests, and `NOT VERIFIED` environment behavior with reason, risk, owner and next action.
+
+## Rollback or migration
+
+Describe rollback, migration/exit behavior, compatibility window, irreversible steps and cleanup.
+
+## Review trigger
+
+Give an expiry date or concrete event. Missing, expired or malformed exception ADRs fail validation.

package/skill/vegastack-arch-guardian/assets/answers-example.json

@@ -0,0 +1,20 @@
+{
+  "profileStatus": "draft",
+  "project": { "name": "example-product", "kind": "saas-product", "lifecycle": "greenfield", "access": "authenticated", "tenancy": "multi-tenant-shared-schema" },
+  "environments": { "production": { "hosting": "cloudflare-opennext" }, "localDevelopment": { "trusted": true, "allowances": ["local-secrets"] } },
+  "capabilities": {
+    "webControlPlane": { "status": "enabled", "ownership": "owned", "versions": { "next": "16.3.0", "node": "24.18.0", "bun": "1.3.14", "openNext": "1.20.2", "betterAuth": "1.6.26" }, "placement": "open-next-worker", "sourceRoots": ["apps/web"], "controls": { "canonicalApi": "rest-openapi", "openapiGenerated": true, "secureCookies": true } },
+    "flutter": { "status": "disabled", "ownership": "not-applicable" },
+    "agents": { "status": "disabled", "ownership": "not-applicable" },
+    "jobs": { "status": "disabled", "ownership": "not-applicable" },
+    "sandbox": { "status": "disabled", "ownership": "not-applicable" },
+    "connectors": { "status": "disabled", "ownership": "not-applicable" },
+    "knowledge": { "status": "disabled", "ownership": "not-applicable" },
+    "modelRouting": { "status": "disabled", "ownership": "not-applicable" },
+    "enterpriseIdentity": { "status": "disabled", "ownership": "not-applicable" },
+    "realtime": { "status": "disabled", "ownership": "not-applicable" },
+    "notifications": { "status": "disabled", "ownership": "not-applicable" },
+    "secrets": { "status": "enabled", "ownership": "owned", "versions": { "openbao": "2.3.2" }, "placement": "external-service", "sourceRoots": ["infra/secrets"], "controls": { "provider": "openbao" } }
+  },
+  "exceptions": []
+}

package/skill/vegastack-arch-guardian/assets/architecture-profile.json

@@ -0,0 +1,25 @@
+{
+  "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": "REQUIRED-CONFIRMED-LIFECYCLE", "access": "REQUIRED-CONFIRMED-ACCESS", "tenancy": "REQUIRED-CONFIRMED-TENANCY" },
+  "environments": {
+    "production": { "hosting": "REQUIRED-CONFIRMED-PRODUCTION-TARGET" },
+    "localDevelopment": { "trusted": true, "allowances": [] }
+  },
+  "capabilities": {
+    "webControlPlane": { "status": "disabled", "ownership": "not-applicable" },
+    "flutter": { "status": "disabled", "ownership": "not-applicable" },
+    "agents": { "status": "disabled", "ownership": "not-applicable" },
+    "jobs": { "status": "disabled", "ownership": "not-applicable" },
+    "sandbox": { "status": "disabled", "ownership": "not-applicable" },
+    "connectors": { "status": "disabled", "ownership": "not-applicable" },
+    "knowledge": { "status": "disabled", "ownership": "not-applicable" },
+    "modelRouting": { "status": "disabled", "ownership": "not-applicable" },
+    "enterpriseIdentity": { "status": "disabled", "ownership": "not-applicable" },
+    "realtime": { "status": "disabled", "ownership": "not-applicable" },
+    "notifications": { "status": "disabled", "ownership": "not-applicable" },
+    "secrets": { "status": "disabled", "ownership": "not-applicable" }
+  },
+  "exceptions": []
+}

package/skill/vegastack-arch-guardian/assets/architecture-profile.schema.json

@@ -0,0 +1,213 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/vegastack/vegastack-skills/main/skills/vegastack-arch-guardian/assets/architecture-profile.schema.json",
+  "title": "VegaStack Architecture Profile v3",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "profileStatus", "foundation", "project", "environments", "capabilities", "exceptions"],
+  "$defs": {
+    "exactVersion": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+(?:\\.[0-9]+)?(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$" },
+    "relativePath": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$" },
+    "nonEmptyStrings": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "serviceContract": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ownerService", "contract", "version", "tenantSecurityBoundary", "identityAudience", "dataResidency", "sloRecovery", "incidentOwner", "compatibility", "migrationExit"],
+      "properties": {
+        "ownerService": { "type": "string", "minLength": 1 },
+        "contract": { "type": "string", "minLength": 1 },
+        "version": { "$ref": "#/$defs/exactVersion" },
+        "tenantSecurityBoundary": { "type": "string", "minLength": 1 },
+        "identityAudience": { "type": "string", "minLength": 1 },
+        "dataResidency": { "type": "string", "minLength": 1 },
+        "sloRecovery": { "type": "string", "minLength": 1 },
+        "incidentOwner": { "type": "string", "minLength": 1 },
+        "compatibility": { "type": "string", "minLength": 1 },
+        "migrationExit": { "type": "string", "minLength": 1 }
+      }
+    },
+    "removal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["durableData", "credentials", "queues", "contracts", "owner", "verification", "rollback"],
+      "properties": {
+        "durableData": { "type": "string", "minLength": 1 },
+        "credentials": { "type": "string", "minLength": 1 },
+        "queues": { "type": "string", "minLength": 1 },
+        "contracts": { "type": "string", "minLength": 1 },
+        "owner": { "type": "string", "minLength": 1 },
+        "verification": { "type": "string", "minLength": 1 },
+        "rollback": { "type": "string", "minLength": 1 }
+      }
+    },
+    "capability": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "ownership"],
+      "properties": {
+        "status": { "enum": ["enabled", "disabled"] },
+        "ownership": { "enum": ["owned", "shared-managed", "external-managed", "not-applicable"] },
+        "versions": {
+          "type": "object",
+          "minProperties": 1,
+          "propertyNames": { "pattern": "^[A-Za-z][A-Za-z0-9]*$" },
+          "additionalProperties": { "$ref": "#/$defs/exactVersion" }
+        },
+        "placement": { "type": "string", "minLength": 1 },
+        "sourceRoots": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/relativePath" } },
+        "contract": { "$ref": "#/$defs/serviceContract" },
+        "controls": { "type": "object", "additionalProperties": { "type": ["string", "boolean", "number", "array"], "items": { "type": "string" } } },
+        "transitionFrom": { "enum": ["enabled", "disabled"] },
+        "removal": { "$ref": "#/$defs/removal" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "status": { "const": "enabled" } }, "required": ["status"] },
+          "then": { "required": ["versions", "placement"], "properties": { "ownership": { "enum": ["owned", "shared-managed", "external-managed"] } } }
+        },
+        {
+          "if": { "properties": { "status": { "const": "disabled" } }, "required": ["status"] },
+          "then": { "properties": { "ownership": { "const": "not-applicable" } } }
+        },
+        {
+          "if": { "properties": { "status": { "const": "enabled" }, "ownership": { "const": "owned" } }, "required": ["status", "ownership"] },
+          "then": { "required": ["sourceRoots"] }
+        },
+        {
+          "if": { "properties": { "ownership": { "enum": ["shared-managed", "external-managed"] } }, "required": ["ownership"] },
+          "then": { "required": ["contract"], "not": { "required": ["sourceRoots"] } }
+        },
+        {
+          "if": { "properties": { "status": { "const": "disabled" }, "transitionFrom": { "const": "enabled" } }, "required": ["status", "transitionFrom"] },
+          "then": { "required": ["removal"] }
+        }
+      ]
+    },
+    "exception": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "ruleId", "paths", "adr", "projectOwner", "status", "verificationType", "rationale", "decision", "risks", "compensatingControls", "verification", "rollbackOrMigration", "review", "foundationDeviationAcknowledged"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^EXC-[0-9]{3,}$" },
+        "ruleId": { "type": "string", "pattern": "^[A-Z]+-[0-9]{3}$" },
+        "controls": { "$ref": "#/$defs/nonEmptyStrings" },
+        "paths": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/relativePath" } },
+        "adr": { "$ref": "#/$defs/relativePath" },
+        "projectOwner": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["active", "withdrawn"] },
+        "verificationType": { "enum": ["static-sentinel", "manual-qualification"] },
+        "rationale": { "type": "string", "minLength": 1 },
+        "decision": { "type": "string", "minLength": 1 },
+        "risks": { "$ref": "#/$defs/nonEmptyStrings" },
+        "compensatingControls": { "$ref": "#/$defs/nonEmptyStrings" },
+        "verification": { "$ref": "#/$defs/nonEmptyStrings" },
+        "rollbackOrMigration": { "type": "string", "minLength": 1 },
+        "review": {
+          "oneOf": [
+            { "type": "object", "additionalProperties": false, "required": ["date"], "properties": { "date": { "type": "string", "format": "date" } } },
+            { "type": "object", "additionalProperties": false, "required": ["event"], "properties": { "event": { "type": "string", "minLength": 1 } } }
+          ]
+        },
+        "foundationDeviationAcknowledged": { "const": true }
+      }
+    }
+  },
+  "properties": {
+    "schemaVersion": { "const": 3 },
+    "profileStatus": { "enum": ["draft", "confirmed"] },
+    "foundation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "baseline", "adoption"],
+      "properties": {
+        "version": { "const": "0.3.0" },
+        "baseline": { "type": "string", "minLength": 1 },
+        "adoption": { "enum": ["supported", "candidate", "deprecated"] }
+      }
+    },
+    "project": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "kind", "lifecycle", "access", "tenancy"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["saas-product", "internal-product", "public-product", "platform-service", "shared-package"] },
+        "lifecycle": { "enum": ["greenfield", "brownfield", "migration", "maintenance"] },
+        "access": { "enum": ["public", "authenticated", "internal", "mixed"] },
+        "tenancy": { "enum": ["none", "single-tenant", "multi-tenant-shared-schema", "multi-tenant-isolated"] }
+      }
+    },
+    "environments": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["production", "localDevelopment"],
+      "properties": {
+        "production": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["hosting"],
+          "properties": { "hosting": { "enum": ["self-hosted", "vercel", "cloudflare-opennext", "external", "none"] }, "region": { "type": "string", "minLength": 1 } }
+        },
+        "localDevelopment": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["trusted", "allowances"],
+          "properties": { "trusted": { "const": true }, "allowances": { "type": "array", "uniqueItems": true, "items": { "enum": ["local-workflow-world", "local-secrets", "local-unsandboxed-code", "single-process"] } } }
+        }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["webControlPlane", "flutter", "agents", "jobs", "sandbox", "connectors", "knowledge", "modelRouting", "enterpriseIdentity", "realtime", "notifications", "secrets"],
+      "properties": {
+        "webControlPlane": { "$ref": "#/$defs/capability" },
+        "flutter": { "$ref": "#/$defs/capability" },
+        "agents": { "$ref": "#/$defs/capability" },
+        "jobs": { "$ref": "#/$defs/capability" },
+        "sandbox": { "$ref": "#/$defs/capability" },
+        "connectors": { "$ref": "#/$defs/capability" },
+        "knowledge": { "$ref": "#/$defs/capability" },
+        "modelRouting": { "$ref": "#/$defs/capability" },
+        "enterpriseIdentity": { "$ref": "#/$defs/capability" },
+        "realtime": { "$ref": "#/$defs/capability" },
+        "notifications": { "$ref": "#/$defs/capability" },
+        "secrets": { "$ref": "#/$defs/capability" }
+      }
+    },
+    "data": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["classes"],
+      "properties": {
+        "classes": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name"],
+            "properties": {
+              "name": { "enum": ["public", "internal", "confidential", "restricted"] },
+              "residency": { "type": "string", "minLength": 1 },
+              "retention": { "type": "string", "minLength": 1 },
+              "owner": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    "objectives": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "availability": { "type": "string", "minLength": 1 },
+        "latency": { "type": "string", "minLength": 1 },
+        "rpoMinutes": { "type": "number", "minimum": 0 },
+        "rtoMinutes": { "type": "number", "minimum": 0 }
+      },
+      "minProperties": 1
+    },
+    "exceptions": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/exception" } }
+  }
+}

package/skill/vegastack-arch-guardian/assets/deployment-review-template.md

@@ -0,0 +1,24 @@
+# Deployment review: release/profile
+
+Delete checklist items for absent capabilities; absence is not a failed control.
+
+## Artifact identity
+
+- Commit:
+- OCI/image/package digests:
+- SBOM/provenance/signatures:
+- Database migration:
+- Architecture profile digest:
+
+## Placement
+
+Verify each enabled owned deployable and each shared/external contract against the selected profile. For Cloudflare/OpenNext, verify owned EVE/jobs stay in external long-running Node/OCI placement.
+
+## Safety gates
+
+- [ ] Backward-compatible API/events and expand/contract migration
+- [ ] Applicable runtime/protocol families are exact and atomically qualified
+- [ ] Applicable tenancy/authz paths are cache-safe and negatively tested
+- [ ] Applicable sandbox/connector/secret boundaries are qualified
+- [ ] Applicable backup/restore evidence is within confirmed RPO/RTO
+- [ ] Rollout, health, rollback, and incident ownership are explicit

package/skill/vegastack-arch-guardian/assets/service-design-template.md

@@ -0,0 +1,33 @@
+# Service design: name
+
+Keep only sections and fields activated by the service. Mark unknown material facts `NOT VERIFIED`; do not fill owners, data classes or objectives with placeholders presented as compliance.
+
+## Ownership and purpose
+
+- Owner:
+- Runtime:
+- Hosting profiles:
+- Data classes:
+- SLO/RPO/RTO:
+
+## Contracts
+
+List only applicable REST/OpenAPI, events, queue jobs, EVE hooks/streams, shared-service contracts and generated clients. Identify idempotency and compatibility rules.
+
+## Tenancy and identity
+
+For shared-schema multi-tenancy, describe workspace derivation, composite keys, every tenant table's `ENABLE/FORCE RLS`, symmetric `USING/WITH CHECK`, transaction-local context, owner/BYPASSRLS separation and pool-reuse evidence. Otherwise state the actual access/tenancy boundary without adding RLS.
+
+For identity-facing services, record secure-cookie/session-cache policy, sensitive database validation, OAuth issuer/audience/code+PKCE/redirect allowlist/refresh rotation/revocation, SCIM organization mapping/deprovision/last-owner behavior, API-key scope, and internal short-lived identity.
+
+## State and failure recovery
+
+Distinguish only state classes the service owns or consumes. Provide applicable retry, dedupe, DLQ, replay, recovery and reconciliation behavior.
+
+## Security and observability
+
+Define secret references/broker lifetime, credential-bearing env/mount prohibitions, egress hosts/CIDRs/ports/DNS/redirect/header policy, logging-sink credential review, redaction, audit events, OTel signals, alerts, and abuse limits.
+
+## Verification
+
+List tests only for enabled boundaries. Mark environment-bound qualification as NOT RUN with reason, risk, owner and next action.

package/skill/vegastack-arch-guardian/assets/threat-model-template.md

@@ -0,0 +1,34 @@
+# Threat model: system or change
+
+Keep only enabled/exposed actors, assets and boundaries. Do not add agent, connector, sandbox, tenant or enterprise-identity threats to a project that lacks those surfaces.
+
+## Scope and assets
+
+List trust zones, tenant data, credentials, durable state, and excluded systems.
+
+## Actors and entry points
+
+List users, support operators, services, agents, connectors, webhooks, MCP servers, sandboxes, and supply-chain inputs.
+
+## Data flows and boundaries
+
+Reference the system-context, identity, sandbox, and evidence diagrams.
+
+Record OAuth/session/SCIM trust transitions, database role and pool boundaries, support elevation, secret-broker exchange, sandbox env/mount/stdout/stderr paths, and every network redirect/DNS/header hop.
+
+## Threats and controls
+
+| ID | Threat | Boundary | Impact | Prevent | Detect | Recover | Owner | Test |
+|---|---|---|---|---|---|---|---|---|
+| T-001 | Cross-tenant object reference | REST/RLS | Restricted data disclosure | Composite keys + authz + RLS | Audit anomaly | Revoke/export/notify | Security | Negative tenant test |
+
+## Residual risk and review triggers
+
+Record accepted risks in linked ADRs and define review events.
+
+## Required adversarial evidence
+
+- Cross-tenant object/join/bulk/export/background access and pool-role reuse
+- OAuth state/PKCE/replay/redirect, session revocation, SCIM deprovision/last-owner, and support expiry
+- Credential injection/logging, webhook replay, SSRF redirect/DNS rebinding/IPv6/link-local, and sandbox proxy/header exfiltration
+- Workflow lost acknowledgement, replayed effects, cancellation race, duplicate admission, and projector cursor rollback

package/skill/vegastack-arch-guardian/references/architecture/agent-product.md

@@ -0,0 +1,22 @@
+# Agent product
+
+Apply this reference only when the `agents` capability is enabled or agent authoring/execution is observed.
+
+## Authoring and publication
+
+- **AGENT-001 — Immutable publication.** Instructions, model policy, tools, skills, connections, channels, schedules, memory, knowledge, structured output, approvals, and evals MAY change in a draft. Publishing **MUST** compile a normalized immutable version.
+- **AGENT-002 — Version-pinned execution.** Every run and conversation **MUST** pin the published agent version, policy version, tool schemas, model policy, knowledge policy, and EVE/Workflow protocol family. Draft edits **MUST NOT** mutate in-flight work.
+- **AGENT-003 — Deterministic compiler.** Compilation **MUST** use canonical ordering, explicit defaults, a schema version, and source digest; identical inputs must produce byte-identical output. Compilation **MUST NOT** resolve plaintext secrets.
+- **AGENT-004 — Risk-based publication.** Publishing **MUST** gate schema compatibility, secret references, permissions, capability escalation, external tools, EVE compatibility, eval regressions, output schemas, approval coverage, egress, quota, and migration impact.
+
+| Draft concern | Published output | Required gate |
+|---|---|---|
+| instructions and model policy | normalized prompt and route | schema and data-class policy |
+| tools, skills, connections | typed capabilities and scopes | risk, secret reference, approval |
+| schedules and channels | admission triggers | tenant, dedupe, timezone, owner |
+| output contract | versioned JSON Schema | conformance evaluation |
+| memory and knowledge | provenance and retention policy | tenant and data-class validation |
+
+Use the lifecycle `draft → preview → publish → production → rollback`. There is no separate staging state. Risk-increasing changes require review; a low-risk text change MAY use policy-approved automation. Rollback activates an earlier immutable version and never rewrites history.
+
+Support private and workspace sharing plus versioned templates. Template copies retain provenance but become independent drafts. Public marketplace moderation, discovery, and billing remain out of scope.

package/skill/vegastack-arch-guardian/references/architecture/ai-cost.md

@@ -0,0 +1,22 @@
+# AI cost
+
+Apply this reference only when metered AI resources exist — model calls, sandbox runtime, embedding or knowledge processing. Cost here is an architecture concern: unattributed spend is an ownership gap, and an unbounded token path is a reliability defect. Billing, pricing, and Stripe remain out of foundation scope.
+
+- **COST-001 — Workspace attribution.** Every model, embedding, sandbox, and knowledge-processing call **MUST** record per-workspace attribution: tokens in/out, cached versus uncached, provider and model pin, feature or agent identity, and run correlation. Aggregate provider invoices are not attribution; the platform must be able to state what any workspace cost yesterday.
+- **COST-002 — Budgets and alerts.** Production AI features **MUST** define token or spend budgets per workspace and per feature, with alert thresholds and an explicit overrun behavior — shed, degrade, or pause visibly. Silent unlimited spend and silent hard-stop are both forbidden; the overrun behavior is a declared product decision.
+- **COST-003 — Cache economics.** Prompt/context caching **SHOULD** be a measured decision: record hit rate and cost delta per route, and structure prompts so stable prefixes actually cache. Caching **MUST NOT** weaken region, retention, or tenant policy (`MODEL-003`); a cache that saves money by crossing a policy boundary fails.
+- **COST-004 — Cost regression gate.** AI feature deploys **MUST** compare cost per interaction (or per run) against the current baseline, like a performance budget. A regression beyond the declared threshold blocks promotion until explained — an intended trade recorded with the change, or a defect fixed. Model swaps, prompt growth, retry amplification, and cache misses are the usual suspects.
+
+## Measuring
+
+| Quantity | Source | Gate use |
+|---|---|---|
+| tokens per run | adapter attribution record | regression baseline |
+| cached share | adapter cache metadata | cache economics |
+| cost per interaction | tokens × pinned model price class | `COST-004` threshold |
+| workspace spend rate | attribution rollup | budget alerts |
+| shed/deferred work | admission records | overrun behavior audit |
+
+Estimate with the provider's published price class for the exact pin; reconcile estimates against provider usage reports on a fixed cadence and alarm on divergence, which usually means unattributed traffic.
+
+Budgets, quotas, and shedding compose with `MLIFE-004`: the same admission edge that protects the provider protects the budget. Retry and fallback paths carry their own attribution so a degraded week is explainable. Cost telemetry is metadata and follows `OBS-002` — amounts and counters, never prompt content.

package/skill/vegastack-arch-guardian/references/architecture/ai-data-boundaries.md

@@ -0,0 +1,19 @@
+# AI data boundaries
+
+Apply this reference when personal data, knowledge ingestion, external model calls, or public-facing AI output exists. It concretizes `SEC-003` and `DATA-003` at the AI trust boundary: personal data moving outward, untrusted content moving inward.
+
+- **PII-001 — Ingestion redaction.** PII detection and classification **MUST** run before content enters embedding, chunking, or knowledge storage; detected PII is redacted, tokenized, or explicitly admitted under the data class policy of the target store. Record the classifier version and decision as provenance so re-scanning after a classifier upgrade is possible. Embeddings of unredacted PII are copies of it and inherit deletion propagation (`DATA-004`).
+- **PII-002 — Prompt boundary.** Before a prompt crosses the trust boundary to an external model provider, PII **MUST** be minimized to what the feature needs and stripped or masked where policy requires; the route's retention and region policy (`MODEL-001`) governs what may cross at all. Memory writes and eval/telemetry sampling are prompt-boundary crossings too — the same redaction applies.
+- **PII-003 — Output moderation.** Public-facing products **MUST** pass model output through a moderation policy before delivery: unsafe-content classes, PII leakage from context or memory, and impersonation of the platform. Internal tools MAY relax categories by declared policy, never by omission. Moderation outcomes are audited metadata; blocked output fails visibly, not silently.
+- **PII-004 — Injection mitigations.** Prompt injection is mitigated by structure, not instructions. Tool results, retrieved chunks, and connector content **MUST** be quarantined as data — spotlighted/delimited with an explicit untrusted marking the prompt template preserves — and **MUST NOT** be able to elevate capabilities: high-impact tool calls (irreversible, external-effect, privileged, or capability-escalating) require the `CONN-001` capability envelope and an approval gate regardless of what any content said. Instructions found inside untrusted spans are never followed into tool selection.
+
+## Boundary placement
+
+| Crossing | Control | Failure mode prevented |
+|---|---|---|
+| document → embedding/knowledge store | `PII-001` classify/redact | PII copies in vectors and chunks |
+| context → external model | `PII-002` minimize/mask | retention outside policy |
+| model → public user | `PII-003` moderation | unsafe or leaking output |
+| tool/retrieval → prompt | `PII-004` quarantine + spotlight | injected instruction execution |
+
+Detection is preventive, not perfect: pair classifiers with data-class defaults (unknown source means restricted), negative tests that plant markers and verify they never reach a provider or a public response, and deletion reconciliation that includes vector stores and cached prompts. Treat retrieved text as untrusted data everywhere, matching `data-memory.md`; an approval gate that a model can talk its way around is prompt-enforced security and fails `SEC-003`.

package/skill/vegastack-arch-guardian/references/architecture/ai-evals.md

@@ -0,0 +1,26 @@
+# AI evaluation
+
+Apply this reference only when agents, prompts, or other model-backed behavior ship to users. A project with no model-backed behavior needs no eval infrastructure.
+
+An eval is a versioned golden dataset plus a scoring method plus an explicit pass threshold, run against a pinned model and prompt. A demo transcript, a vibe check, or an unpinned notebook run is not an eval and produces no evidence.
+
+- **EVAL-001 — Eval definition.** Every evaluated behavior **MUST** define a golden dataset with provenance and tenant-safe sourcing, a deterministic scoring method or declared judge configuration, and numeric pass/regression thresholds recorded before the run, not chosen after it.
+- **EVAL-002 — Promotion gate.** Changes to agent instructions, prompts, model policy, routed model, tool schemas, or knowledge policy **MUST** pass offline regression evals against the golden datasets before publish or promote. A threshold regression blocks promotion; overriding it is a project-owner accepted risk, not a pass.
+- **EVAL-003 — Versioned datasets.** Eval datasets, scoring configuration, and thresholds **MUST** be versioned alongside the prompts and agent versions they gate, so any historical eval result can be reproduced from its exact inputs. Dataset edits that change pass rates are behavior changes and go through the same review as prompt changes.
+- **EVAL-004 — Online sampling.** Production eval sampling **MUST** respect workspace data policy, retention, and redaction before any live interaction enters a dataset or judge prompt. Sampled cases feed dataset growth through review, never automatically.
+
+## Judge models
+
+Model-as-judge scoring is permitted with declared caveats: pin the judge model and prompt version, measure judge agreement against a human-labeled slice before trusting it, and re-baseline whenever the judge model changes. Judge scores are relative evidence — they compare candidates under one fixed judge; they do not certify absolute quality. Do not use the model under test as its own judge, and do not let judge drift silently move a threshold.
+
+## Operating the gate
+
+| Change | Required eval evidence |
+|---|---|
+| prompt or instruction edit | offline regression pass on affected datasets |
+| model or route change | full regression pass plus cost/latency comparison |
+| tool schema change | tool-selection and output-conformance pass |
+| knowledge policy change | retrieval-grounded answer pass |
+| dataset edit | reviewed diff and re-baselined thresholds |
+
+Keep datasets small enough to run in CI and grow them from triaged production failures, not synthetic bulk. Record every gate run with dataset version, model, prompt version, scores, and outcome so `AGENT-004` publication gates can cite it. Offline pass plus bounded online sampling is the evidence pair; neither alone qualifies a behavior change for tenants.