@vegastack/skills 0.4.0 → 0.6.0

package/skill/arch-guardian/SKILL.md

@@ -1,84 +0,0 @@
----
-name: 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 an ADR or a .vegastack/architecture.json profile, threat modeling, planning a migration, or checking dependency and source drift. Advises contextually by declared tier (prototype, production, enterprise) and enabled capabilities; recommends the smallest architecture that meets the requirement and produces evidence-backed advisory reports, never CI gates. Covers web-only, Flutter, agentic and non-agentic, single- and multi-tenant, internal, client, and package projects.
----
-
-# VegaStack Architecture Guardian
-
-Act as the project's senior architecture advisor. Apply only enabled capabilities at the declared tier. Recommend; never gate. Never invent compliance or project facts. There is no exception machinery: a team that departs from a recommendation records the decision, and you keep reporting it honestly as accepted risk.
-
-## Start every task
-
-1. Identify the actual decision, its scope, and how expensive it is to reverse.
-2. Read the profile (`.vegastack/architecture.json`) and repository evidence before asking questions. Keep read-only work read-only; never create a profile or artifact merely because it is absent.
-3. Note the **tier** (`prototype` | `production` | `enterprise`) — it decides which concerns apply. If no profile exists, ask for the tier (or state the assumed one) before recommending.
-4. Separate facts, constraints, assumptions, preferences, and recorded team decisions. Distinguish current, target, and migration state.
-5. Ask at most three material questions at a time. If unanswered, proceed with bounded assumptions and the smallest architecture that meets stated requirements — every proposed moving service names the trigger that justifies it.
-6. Read only the directly relevant references below. Use the committed profile, designs, and ADRs as architecture memory; never rely on hidden chat state.
-7. Prioritize security/correctness, recovery, ownership, contracts, operability, delivery, then optional optimization. Make one primary recommendation and identify the rejected alternative.
-
-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 recommendation and at most one material risk. No section headers, no report.
-- **Design reviews, ADRs, migration plans:** use the [advisory report contract](references/advisory-report.md): per-area grades (`sound`/`attention`/`at-risk`), severity-ranked findings (`critical`/`production-gate`/`enterprise-gate`/`consider`), each with cited evidence and its principle ID, plus questions and not-verified items. No finding without evidence; detection is never a claim of absence.
-
-## Route progressively
-
-| Need | Read |
-|---|---|
-| operating model, tiers, minimum viable architecture, profiles | [foundation](references/architecture/foundation.md), [profile and governance](references/profile-governance.md) |
-| greenfield, brownfield, review, migration workflows | [adaptive workflows](references/workflows.md) |
-| review output format and evidence recipes | [advisory report](references/advisory-report.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, secrets, 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) |
-
-For current detail beyond a pinned claim, [refresh/sources.json](refresh/sources.json) is also the research index: fetch the affected source's `llms` or `docsIndex` URL (or use an available docs MCP). For design reviews and recommendations that lean on a **critical** source (`critical: true`), check freshness — `node <skill-dir>/scripts/refresh-evidence.mjs --topics <affected-topics>` when online, or report the claim as not verified when offline past its `thresholdDays`. Plain questions answer from the shipped snapshot with a one-line staleness caveat. Consult [foundation compatibility](references/foundation-compatibility.json) for version baselines.
-
-## Execute the task-specific workflow
-
-- **Greenfield:** Follow the adaptive intake in [workflows](references/workflows.md): interview (tier first), recommend one capability set and topology sized by minimum viable architecture, name immediate/deferred decisions and triggers, and offer a slim profile draft after confirmation.
-- **Brownfield/review:** Inspect instructions, manifests/locks, deployables, schemas/migrations, auth, APIs, jobs, infra, ADRs, and runbooks before interviewing. Produce an advisory report; prefer controlled migration over rewrites.
-- **ADR/design/threat/deploy:** Use the relevant asset only after write authorization; an ADR is a decision record, never a waiver.
-- **Continuous work:** Load only affected references. Do not force absent capabilities or higher-tier concerns into scope.
-- **Source drift:** Follow [refresh/REFRESH.md](refresh/REFRESH.md). Refresh only affected topics.
-
-## Profiles and mutation safety
-
-The committed profile lives at `.vegastack/architecture.json` (schema v4, ~12 lines; legacy names are 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 .
-node <skill-dir>/scripts/profile-tool.mjs migrate .vegastack/architecture.json --dir .   # v3 -> v4 draft
-```
-
-`inspect` prints a compact summary; `--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 (`--write` to apply). Validate with:
-
-```sh
-node <skill-dir>/scripts/validate-profile.mjs .vegastack/architecture.json
-```
-
-## Guardrails
-
-- Tiers gate concerns, never tools. Never require a tool when only the invariant matters: the mechanism (platform secret store vs OpenBao, cron vs pg-boss, in-process loop vs EVE at prototype) is chosen by named triggers and recorded per project.
-- Never require SQL/RLS, Better Auth, Flutter, EVE, pg-boss, sandbox, connectors, enterprise identity, realtime, notifications, or knowledge when their activation condition is absent — and never surface enterprise-tier concerns as defects to a prototype/production project; report them as that tier's gate.
-- Challenge proposals and defaults when evidence warrants. Choose the smallest architecture meeting current requirements and measured objectives.
-- 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/arch-guardian/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "VegaStack Architecture Guardian"
-  short_description: "Tier-aware architecture advisor for VegaStack projects"
-  default_prompt: "Use $arch-guardian to make one scoped architecture recommendation for this project at its declared tier, without assuming absent capabilities or requiring tools whose triggers are unmet."

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

@@ -1,25 +0,0 @@
-# ADR-NNN: Decision title
-
-An ADR is an optional decision record for consequential architecture choices — including deliberate departures from a guardian recommendation. Nothing gates on it; it exists so future readers know the decision was deliberate, who owns it, and when to revisit it.
-
-- Status: proposed | accepted | superseded | rejected
-- Date: YYYY-MM-DD
-- Owner: accountable person
-- Related-Principles: canonical rule IDs this decision touches, or `none`
-- Revisit: YYYY-MM-DD or a concrete event, or `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 the reason — including, for any new moving service, the trigger that justifies it.
-
-## Risks
-
-Describe each accepted risk, who accepts it, and what is affected. If this departs from a guardian recommendation, say so plainly; the guardian will keep reporting it as accepted risk in reviews.
-
-## Verification and rollback
-
-What evidence supports the decision (label unverified claims honestly), how it would be rolled back or migrated away from, and any irreversible steps.

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

@@ -1,10 +0,0 @@
-{
-  "project": { "name": "example-product", "kind": "saas", "tier": "production", "tenancy": "multi-tenant-shared-schema" },
-  "hosting": "cloudflare-opennext",
-  "capabilities": ["web", "jobs"],
-  "notes": [
-    "Better Auth is the identity library",
-    "PostgreSQL is the system of record; RLS forced on tenant tables",
-    "Secrets live in the platform's managed secret store (trigger review before enterprise tier)"
-  ]
-}

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

@@ -1,13 +0,0 @@
-{
-  "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": []
-}

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

@@ -1,31 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/vegastack/vegastack-skills/main/skills/arch-guardian/assets/architecture-profile.schema.json",
-  "title": "VegaStack Architecture Profile v4",
-  "description": "Slim advisor memory: confirmed project facts, the declared tier, and the enabled capability list. Versions are read from lockfiles and manifests at advice time, never duplicated here.",
-  "type": "object",
-  "additionalProperties": false,
-  "required": ["schemaVersion", "project", "hosting", "capabilities"],
-  "properties": {
-    "schemaVersion": { "const": 4 },
-    "foundationVersion": { "type": "string", "minLength": 1 },
-    "project": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["name", "kind", "tier", "tenancy"],
-      "properties": {
-        "name": { "type": "string", "minLength": 1 },
-        "kind": { "enum": ["saas", "internal-tool", "client-site", "api", "package"] },
-        "tier": { "enum": ["prototype", "production", "enterprise"] },
-        "tenancy": { "enum": ["none", "single-tenant", "multi-tenant-shared-schema", "multi-tenant-isolated"] }
-      }
-    },
-    "hosting": { "enum": ["self-hosted", "vercel", "cloudflare-opennext", "external", "none"] },
-    "capabilities": {
-      "type": "array",
-      "uniqueItems": true,
-      "items": { "enum": ["web", "flutter", "agents", "jobs", "sandbox", "connectors", "knowledge", "models", "realtime", "notifications", "enterprise-identity"] }
-    },
-    "notes": { "type": "array", "items": { "type": "string", "minLength": 1 } }
-  }
-}

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

@@ -1,24 +0,0 @@
-# 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/arch-guardian/assets/service-design-template.md

@@ -1,33 +0,0 @@
-# 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/arch-guardian/assets/threat-model-template.md

@@ -1,34 +0,0 @@
-# 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/arch-guardian/references/advisory-report.md

@@ -1,65 +0,0 @@
-# Advisory report contract
-
-The advisory report is the guardian's review output. It is produced by the agent (not a checker script), is consumable by humans and by automation (a ship skill may parse the JSON block), and carries no gating semantics: findings inform decisions, the team decides.
-
-## Severities
-
-| Severity | Meaning |
-|---|---|
-| `critical` | security, correctness, or data-loss defect — fix now at any tier |
-| `production-gate` | must be addressed before or at production tier |
-| `enterprise-gate` | required only at enterprise tier |
-| `consider` | improvement; explicitly optional |
-
-A finding's severity comes from the violated rule's tier floor relative to the project's declared tier: a rule at or below the current tier that is violated is `critical` when it is a security/correctness invariant, otherwise it reports at its own tier gate. Rules above the current tier report as that tier's gate, never as failures.
-
-## Evidence discipline
-
-These rules are hard requirements; they exist to make false positives structurally difficult.
-
-1. Every finding cites concrete evidence: `file:line`, a config key, a schema statement, or a fetched source URL. A claim without evidence is a **question**, listed separately — never a finding.
-2. Every finding names the principle or rule ID it derives from, so "why does this apply to me" is always answerable from the report.
-3. Detection is never a claim of absence. "No RLS statements found in `db/`" is a question unless every schema/migration file was actually read.
-4. Behavior that cannot be verified in context (runtime, provider, recovery) is listed under `notVerified` with a reason and a suggested verification — never asserted either way.
-5. Repeated identical findings are capped with a count; a report is a decision aid, not a wall of noise.
-6. Grades summarize, they do not gate: `sound` / `attention` / `at-risk` per reviewed area, plus a one-line overall assessment. There is no REJECT vocabulary; a deliberate, recorded team decision the guardian disagrees with is reported as `accepted risk — guardian recommends revisiting`, with the reason.
-
-## Report shape
-
-Markdown for humans, ending with one fenced `json` block for automation:
-
-```json
-{
-  "schemaVersion": 1,
-  "project": "name",
-  "tier": "production",
-  "overall": "one-line assessment",
-  "grades": { "identity": "sound", "tenancy": "attention" },
-  "findings": [
-    {
-      "severity": "production-gate",
-      "principle": "TEN-002",
-      "summary": "one-sentence defect statement",
-      "evidence": ["db/001-tenant.sql:14"],
-      "suggestedAction": "what to change"
-    }
-  ],
-  "questions": ["things the review could not determine from evidence"],
-  "notVerified": [{ "claim": "PITR restore works", "reason": "not executed", "verify": "run a restore drill" }]
-}
-```
-
-## Evidence recipes
-
-Deterministic searches worth running during a review (read the hits before citing them — a match is a lead, not a finding):
-
-- **Tenant tables without RLS**: for each `CREATE TABLE` with a `workspace_id` column, confirm matching `ALTER TABLE … ENABLE ROW LEVEL SECURITY` and `FORCE ROW LEVEL SECURITY` statements exist, and that policies do not reduce to `USING (true)`.
-- **Composite tenant keys**: tenant-owned unique/foreign keys should include `workspace_id`; a bare `id` uniqueness on a tenant table is a lead for TEN-001.
-- **Plaintext secrets**: search tracked files for private key blocks, `Authorization: Bearer` literals, and provider key prefixes; check `.env*` files are gitignored and `.env.local` stays local-only.
-- **Session-state tenancy**: `SET (?!LOCAL)` / `set_config(..., false)` in SQL near tenant context is a lead for TEN-003 (context must be transaction-local).
-- **Runtime placement**: EVE/`@workflow/*` or `pg-boss` imports inside a web bundle or OpenNext worker source root are leads for RUN-001/RUN-002.
-- **Cookie/CSRF posture**: auth configuration disabling secure cookies, CSRF, or origin checks is a lead for AUTH-003.
-- **Sandbox egress**: sandbox configuration without an explicit allowlist (deny-by-default) is a lead for SBX-003.
-- **Unpinned models**: `latest` or alias model identifiers in production routes are leads for MLIFE-001.
-
-Respect `.guardianignore` (path prefixes, one per line) when the project provides one, and say in the report which paths were excluded or skipped.

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

@@ -1,22 +0,0 @@
-# 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/arch-guardian/references/architecture/ai-cost.md

@@ -1,24 +0,0 @@
-# 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.
-
-Minimum viable form by tier — prototype: none required. Production: attribution logging (`COST-001`) plus a hard spend cap or alert. Enterprise: full budgets, cache economics, and the regression gate.
-
-- **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/arch-guardian/references/architecture/ai-data-boundaries.md

@@ -1,21 +0,0 @@
-# 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-004` (injection quarantine) applies at every tier untrusted content reaches a prompt; `PII-001`/`PII-002` bind from production tier; `PII-003` moderation depth scales from a basic unsafe-content pass at production to full policy classes at enterprise.
-
-- **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/arch-guardian/references/architecture/ai-evals.md

@@ -1,28 +0,0 @@
-# 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.
-
-Minimum viable form by tier — prototype: none required. Production: one golden dataset and threshold for the main model-backed behavior, run before promoting prompt/model changes. Enterprise: the full regime below, including online sampling policy.
-
-- **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.

package/skill/arch-guardian/references/architecture/connectors-sandbox.md

@@ -1,39 +0,0 @@
-# Connectors and sandbox
-
-Apply connector rules only to enabled/observed connectors, MCP or webhooks. Apply sandbox rules only to enabled/observed untrusted execution. Ordinary trusted application code does not activate a sandbox requirement.
-
-## Connector boundary
-
-- **CONN-001 — Capability-bound tools.** Every tool call **MUST** carry an expiring capability bound to audience, resource, action, workspace, data class, risk class, and approval requirement. Subagents receive attenuated capabilities and no ambient credentials.
-- **CONN-002 — Connector credentials.** Access and refresh tokens **MUST** remain encrypted references outside agents and sandboxes. Refresh **MUST** be single-flight and revoke on disable, deprovision, or policy loss.
-- **CONN-003 — Trusted outbound fetch.** Connector and MCP HTTP **MUST** revalidate every redirect, couple DNS validation to the actual connection, reject private/loopback/link-local/metadata/multicast targets, strip cross-origin credentials, and bound method, port, path, body, response, and time.
-- **CONN-004 — MCP token separation.** MCP access tokens **MUST** be resource/audience-bound and validated on every request; because MCP `2026-07-28` accepts or rejects each request independently, validation **MUST NOT** rely on session or handshake state. An inbound token **MUST NOT** be forwarded to an upstream API; use a separate downstream credential and per-client consent. [MCP-SPEC]
-- **CONN-005 — Webhook admission.** Webhook ingress **MUST** verify a signature over the raw bounded body, enforce timestamp/replay windows and event dedupe, derive the workspace from server-owned mappings, and durably admit before acknowledgement.
-
-Classify tools as read-only, reversible write, irreversible/external effect, privileged administrative, or untrusted execution. Default-deny unknown tools. High-risk or capability-escalating calls require an EVE approval gate with reason, expiry, actor, decision, and immutable audit.
-
-Target MCP spec revision `2026-07-28`: each request declares its protocol version via `io.modelcontextprotocol/protocolVersion` in `_meta` (mirrored in the `MCP-Protocol-Version` header on Streamable HTTP), servers implement the mandatory `server/discover` RPC advertising supported versions, capabilities, and identity, and unsupported versions fail with `UnsupportedProtocolVersionError` for a retry at a mutually supported revision. <!-- source: MCP-SPEC --> Track the spec's deprecated-features registry; deprecated features carry a minimum twelve-month removal window (ninety days expedited), so plan migrations from it rather than from breakage. <!-- source: MCP-SPEC --> [MCP-SPEC]
-
-## Sandbox boundary
-
-- **SBX-001 — Untrusted execution.** Production untrusted code **MUST** use a provider sandbox uniquely bound to workspace, run, and trust class. Local execution is trusted-development only.
-- **SBX-002 — Credential-free sandbox.** A sandbox **MUST NOT** receive database, secret-store, model-provider, connector-refresh, or ambient object-store credentials. Trusted broker code MAY inject an upstream credential only after validating a short-lived capability and must never return it. [tier: all]
-- **SBX-003 — Default-deny egress.** Egress **MUST** default deny. Trusted policy **MUST** constrain destination, method, path, headers, redirects, body, and response; discard sandbox-provided `Authorization`, cookies, and `Host` before reconstructing the request. [tier: all]
-- **SBX-004 — Disposable execution.** Enforce CPU, memory, disk, process, network, output, and time quotas plus cleanup and sweeper reconciliation. Correctness and durable state **MUST NOT** depend on sandbox process or filesystem survival.
-- **SBX-005 — Provider contract.** A provider **MUST** declare isolation, lifecycle, quotas, network controls, file transfer, streaming, cleanup, region/jurisdiction, and capability stability; conformance tests determine support.
-
-```mermaid
-flowchart LR
-  Eve["EVE with scoped capability"] --> Broker["Trusted broker"]
-  Broker --> Policy["Tenant, action, destination policy"]
-  Policy --> Sandbox["Disposable sandbox"]
-  Sandbox --> Request["Credential-free request intent"]
-  Request --> Broker
-  Broker --> Upstream["Allowlisted upstream with injected credential"]
-  Sandbox -. blocked .-> Private["Private, metadata, or arbitrary network"]
-  Sandbox -. no access .-> Secrets["Database, OpenBao, provider keys"]
-```
-
-Cloudflare Sandbox is preferred and Modal is the main alternative behind `SandboxProvider`. Cloudflare outbound Internet is open unless explicitly restricted: set `allowedHosts`, which becomes a deny-by-default allowlist once configured, plus `deniedHosts` for explicit blocks; route credentialed egress through outbound handlers, changeable at runtime via `setOutboundHandler()`; per-instance TLS interception (an ephemeral CA per sandbox, available since `@cloudflare/sandbox` 0.8.9) extends handler policy to HTTPS. <!-- source: CF-SANDBOX --> The API accepts glob patterns; SBX-003 still requires deny-by-default egress without wildcards, so allowlists pin exact hosts. Modal also requires explicit network restriction. [CF-SANDBOX] [MODAL-SANDBOX]
-
-Test IPv4/IPv6, DNS rebinding, redirect hops, header stripping, token expiry/replay, cross-tenant sandbox IDs, credential-bearing errors/responses, quota, timeout, cancellation, crash, and cleanup.

package/skill/arch-guardian/references/architecture/data-memory.md

@@ -1,25 +0,0 @@
-# Data and memory
-
-Apply each rule only to its enabled/observed data capability. A stateless/shared-package project need not add PostgreSQL, knowledge, memory, object storage or Valkey.
-
-- **DATA-001 — System of record.** PostgreSQL **MUST** be the authoritative business store. Valkey MAY accelerate measured hot paths but correctness **MUST NOT** depend on it. [POSTGRES-DOCS]
-- **DATA-002 — Knowledge storage.** Default knowledge retrieval **MUST** use tenant-scoped PostgreSQL FTS plus pgvector; binary objects use an S3-compatible abstraction with checksums and version IDs. [PGVECTOR] [S3-SPEC]
-- **DATA-003 — Separate state classes.** EVE conversation state, curated durable memory, and provenance-bearing knowledge **MUST** remain distinct. Model-generated memory is a proposal that passes policy, dedupe, classification, provenance, and retention before persistence.
-- **DATA-004 — Lifecycle policy.** Every data class **MUST** define purpose, location, retention, export, deletion propagation, backup expiry, legal-hold behavior, and owner. Deletion **MUST** be tracked and reconciled across PostgreSQL, objects, indexes/vectors, caches, telemetry, and downstream connectors.
-- **DATA-005 — Object boundary.** Object upload/download **MUST** use short-lived scoped access, size/type validation, encryption, and applicable malware scanning. Production buckets and long-lived object credentials **MUST NOT** be mounted into a sandbox.
-
-| Data | Authoritative owner | Required metadata |
-|---|---|---|
-| business and tenant records | PostgreSQL | workspace, policy version, audit correlation |
-| agent execution | EVE/Postgres World | session, step/event cursor, published version |
-| curated memory | application PostgreSQL | provenance, classifier, retention, supersession |
-| knowledge chunks | PostgreSQL/pgvector | source, extraction and embedding versions, access policy |
-| binary objects | S3-compatible store | workspace, checksum, version, data class, retention |
-
-Authorize before retrieval and before producing snippets. Enforce workspace/data policy in SQL/RLS, include provenance and source timestamps, version extraction/chunking/embedding, and treat retrieved text as untrusted data rather than instructions.
-
-Residency claims require enforceable jurisdiction restrictions and tested placement; provider hints alone are insufficient. Legal hold suspends ordinary deletion only for the scoped records and must remain auditable.
-
-Add Valkey only after a measured cache or coordination benefit exists and the PostgreSQL-backed correctness path passes without it.
-
-The pinned baseline is the PostgreSQL 17.x series; PostgreSQL 18 (GA, 18.4 current minor) is the candidate upgrade horizon and adopting it requires re-qualifying RLS, pg-boss, and Workflow World behavior for the exact tuple. <!-- source: POSTGRES-DOCS -->

package/skill/arch-guardian/references/architecture/delivery-operations.md

@@ -1,34 +0,0 @@
-# Delivery and operations
-
-Apply test and release boundaries only to enabled capabilities and declared deployables. Never report an absent capability as an untested control.
-
-- **DEL-001 — Boundary verification.** Tests **MUST** cover every applicable enabled boundary—contracts/code generation, RLS/tenant negatives, EVE replay/evals, pg-boss crash/retry, sandbox egress/secrets, web/mobile E2E, performance, restore, and dependency failure. Static sentinels never substitute for runtime qualification.
-- **DEL-002 — Compatible migrations.** Migrations **MUST** use expand, migrate, and contract: add backward-compatible schema, deploy compatible code, backfill idempotently with progress, verify, switch reads/writes, and remove only after the rollback window.
-- **DEL-003 — Migration safety.** Destructive migrations **MUST NOT** run as unreviewed application startup side effects. Estimate locks/rewrites, bound batches, verify backup/restore, expose progress, and define rollback or forward-fix.
-- **DEL-004 — Release identity.** Release artifacts **MUST** record source/lock/toolchain digests, exact dependencies, generated outputs, tests and skips, package/container digests, SBOM, provenance, signatures, migrations, profile/ADR identity, target, and rollback artifact. [tier: enterprise]
-- **DEL-005 — Relevant freshness.** For design reviews and recommendations leaning on pinned claims, stale or unavailable critical security, auth, tenancy, durability, secrets, and deployment evidence **MUST** be reported as not verified rather than asserted; plain questions answer from the shipped snapshot with a staleness caveat, and unrelated work stays on the fast path.
-- **DEL-006 — Honest verification.** Environment-bound replay, isolation, failover, restore, and provider tests **MUST** be reported as `NOT RUN` when not executed, with reason, risk, owner, and next action.
-
-## Required test boundaries
-
-| Boundary | Minimum evidence |
-|---|---|
-| API/schema | Zod → OpenAPI → clients deterministic and compatible |
-| identity/tenancy | session/revocation, OAuth/PKCE, SCIM, composite keys, per-table RLS negatives |
-| execution | exact tuple, publication pin, approval, replay, waits, effects, cancellation |
-| admission/jobs | atomic enqueue, dedupe, retry/heartbeat, DLQ, ordinary job separation |
-| connectors/sandbox | SSRF/replay, capability scope, no credentials, egress, quota, cleanup |
-| clients/channels | reconnect, offline mutation, push/deep links, localization, accessibility |
-| operations | load, process/dependency/cell loss, PITR/restore, migration rollback |
-
-CI fails on hard-rule violations, nondeterministic generated output, broken references/source IDs, stale critical evidence, unsupported placement, incompatible migrations/contracts, or security/durability regressions. Flaky critical tests are defects and must not be silently retried to green.
-
-## Rollout and maintenance
-
-Roll out by profile, cell, or cohort with health gates; preserve protocol compatibility during mixed versions; drain long-running workers; and keep code/config rollback independent where schema permits.
-
-Bootstrap by creating the slim profile, declaring the tier and hosting, validating the profile, refreshing affected sources, checking generated contracts, and completing threat/deployment review at the tier's depth.
-
-Doctor verifies Node availability, profile structure, and installed-skill integrity. It does not prove database connectivity/extensions, source freshness, secret-store identity, generated-contract drift, or live object/sandbox/model behavior.
-
-Use the bundled ADR, threat-model, service-design, and deployment-review templates when relevant. Maintain incident documentation at the tier's depth and revisit recorded deviations on their declared triggers; setup scripts never create paid or cloud resources implicitly.

package/skill/arch-guardian/references/architecture/durable-execution.md

@@ -1,45 +0,0 @@
-# Durable execution
-
-Apply EVE/Workflow/AgentRun rules only when agents are enabled or observed. Apply pg-boss rules only when owned agent admission or ordinary jobs are enabled or observed. A non-agentic project does not require EVE, Workflow World, AgentRun or pg-boss.
-
-Minimum viable form by tier — prototype: agents MAY run as simple in-process loops with at-least-once effects and a named migration path to durable execution; ordinary background work MAY use plain cron/queue primitives. The `DUR-*` ownership and qualification rules bind from production tier, where crash recovery and replay become real requirements — the trigger for EVE/pg-boss is durable multi-step agent work that must survive restarts, not the presence of agents alone.
-
-## Exclusive ownership
-
-- **DUR-001 — One workflow owner.** EVE with its compatible PostgreSQL Workflow World **MUST** exclusively own durable agent sessions, steps, waits, approvals, continuations, hooks, streams, and tool-loop state. Do not introduce a second workflow engine, tool loop, HITL store, or execution queue.
-- **DUR-002 — Exact production tuple.** Production **MUST** pin `eve@0.29.5` and `@workflow/world-postgres@5.0.0-beta.30`; the lock **MUST** resolve its compatible `@workflow/world@5.0.0-beta.23` and `@workflow/world-local@5.0.0-beta.32`. Upgrade the family atomically. Local Workflow Worlds/files are development-only and forbidden in production. [EVE-PINNED] [WORKFLOW-PG]
-- **DUR-003 — Admission owner.** pg-boss **MUST** own transactional application admission and ordinary background jobs only. It **MUST NOT** model EVE execution state or use flow features as a second agent workflow engine. [PGBOSS-1227]
-- **DUR-004 — Product record.** AgentRun **MUST** retain authoritative product/audit inputs and a cursor-versioned projection of EVE events. Projection is required behavior in a trusted long-running plane, not a required standalone deployable. It **MUST** declare its source, direction, reconciliation, and monotonic update rule; it is not replay truth.
-- **DUR-005 — Transaction boundary.** The control plane **MUST** create AgentRun and one pg-boss admission job in the same PostgreSQL transaction when possible. The job carries the deterministic admission key and AgentRun records pending/accepted audit state plus the unique EVE session reference. Use an outbox only when a transaction or database boundary prevents atomic enqueue.
-- **DUR-006 — External effects.** Every retried external effect **MUST** use an idempotency/effect fence and reconciliation. Job claiming or step replay is not proof of exactly-once external side effects.
-- **DUR-007 — Replay qualification.** Before the production tier, durable execution **MUST** reproduce crash behavior before/after checkpoints and effects, completed-step replay, interrupted-step idempotency, approval persistence, wait/resume, cancellation, cursors, mixed-version migration, and PostgreSQL recovery for the exact tuple.
-- **DUR-008 — Tenant-qualified World.** Before shared-database production, every tenant-bearing Workflow World record and service role **MUST** satisfy `TEN-001` through `TEN-004`. A tuple that cannot preserve that boundary **MUST** fail qualification; RLS weakening, owner roles, and `BYPASSRLS` are forbidden.
-- **DUR-009 — Workflow exit contract.** Owning the workflow engine does not exempt it from provider neutrality: production durable execution **MUST** maintain an exit/migration contract naming the engine-specific constructs in use (sessions, steps, waits, approvals, hooks, streams), an exportable schema for durable session and event state, a drain/quiesce procedure, and a documented migration path with rollback to a replacement engine or major version. The contract is reviewed with the same cadence as the pinned tuple; a lock without an exit plan is accepted risk, not neutrality.
-
-```mermaid
-sequenceDiagram
-  participant API as Control plane
-  participant PG as PostgreSQL and pg-boss
-  participant Eve as EVE worker
-  participant World as Postgres Workflow World
-  participant Tool as External effect
-  API->>PG: AgentRun and admission job in one transaction
-  PG->>Eve: dispatch workspace and admission key
-  Eve->>World: create or find durable session
-  Eve->>Tool: approved, fenced effect
-  Tool-->>Eve: result
-  Eve->>World: checkpoint and emit event
-  World-->>PG: trusted projection handler advances AgentRun cursor
-```
-
-## Admission and recovery
-
-Use `(workspace_id, admission_key)` as the logical start key. After a lost acknowledgement, look up the same EVE session before retrying; a retry never creates another logical run. The trusted EVE-event projection handler, not the admission job, supplies terminal execution state; it MAY run inside an existing trusted long-running deployable.
-
-Use pg-boss groups/priority plus measured wait age for ordinary tenant fairness. Add a separate selector/lease table only when reproduced strict global quota or starvation requirements exceed pg-boss semantics; that extraction needs an ADR and must not model EVE execution.
-
-Configure bounded retries/backoff, heartbeats, dedupe, attempt history, DLQ/redrive, inspect/cancel operations, and graceful shutdown. Redrive reuses the same admission key and effect fence. LISTEN/NOTIFY MAY reduce latency, but polling remains the safety path. [PGBOSS-1227]
-
-Do not assume same-session FIFO unless reproduced for the exact tuple.
-
-Qualification evidence remains tuple-specific and environment-specific. The pinned `eve@0.29.5` tuple is beta; <!-- source: EVE-PINNED --> `@workflow/world-postgres` remains a `5.0.0-beta` line, and the workflow SDK reaching GA is a mandatory human re-review trigger for `DUR-002` and `DUR-009` — re-evaluate the pin, the migration path, and the exit contract at that point rather than upgrading silently. <!-- source: WORKFLOW-PG -->