@vegastack/skills 0.5.0 → 0.6.0

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 -->

package/skill/arch-guardian/references/architecture/flutter.md

@@ -1,26 +0,0 @@
-# Flutter client
-
-Apply this reference only when the `flutter` capability is enabled or Flutter code is observed.
-
-## Architecture
-
-- **MOB-001 — Delegated mobile identity.** Flutter **MUST** use Better Auth OAuth 2.1/OIDC authorization code with S256 PKCE, discovery, consent, refresh rotation, and revocation. Better Auth Bearer session transport is not the mobile foundation. [BETTERAUTH-OAUTH] [APP-AUTH]
-- **MOB-002 — Generated client.** Flutter **MUST** consume the generated OpenAPI client and must not maintain parallel request/response types.
-- **MOB-003 — Local secrets.** Refresh tokens and device-bound secrets **MUST** use platform secure storage; logs, analytics, crash reports, deep links, and ordinary local databases **MUST NOT** contain them. [tier: all]
-- **MOB-004 — Push and link boundary.** Push payloads **MUST NOT** contain sensitive content or credentials; clients authenticate and fetch authoritative state. Universal/app links **MUST** validate scheme, host, path, state, expiry, and authenticated tenant before navigation.
-
-Organize code by Riverpod feature modules with declarative routing and online-first repositories. Expose loading, stale, error, retry, and conflict state rather than hiding network state. [FLUTTER-DOCS] [RIVERPOD-DOCS]
-
-Apply pinned claims to the Flutter 3.44 stable series (Dart 3.12), the current stable baseline; adopting a newer stable is source drift that requests scoped review, matching how other foundation-compatibility families handle version advances. <!-- source: FLUTTER-DOCS -->
-
-## Network and local state
-
-Attach access tokens only to allowlisted API origins. Refresh through one coordinated path; on reuse, revocation, or invalid grant, clear credentials and require authentication. Bind idempotency keys to mutating commands and reconcile optimistic state with the server.
-
-Classify cached data by sensitivity and retention. Encrypt confidential caches, scope them to account and workspace, purge them on sign-out, revocation, workspace removal, or policy change, and make schema migrations reversible or safely destructive.
-
-## Push, links, and release
-
-Treat notifications as hints and deduplicate them by event ID. [FCM-DOCS] [APNS-DOCS]
-
-Support localized UI and templates, RTL, IANA timezones, accessibility semantics, font scaling, and locale-aware formatting. Release gates should cover generated-client drift, OAuth/PKCE, token refresh/revocation, offline mutation recovery, tenant switching, push/deep links, storage purge, localization, and accessibility.

package/skill/arch-guardian/references/architecture/foundation.md

@@ -1,31 +0,0 @@
-# Foundation
-
-## Operating model
-
-VegaStack projects — internal or client — declare confirmed facts in a slim committed profile: kind, **tier**, tenancy, hosting, and the enabled capability list. The guardian is an advisor: it interviews, observes, recommends, and reviews. It never gates, and it has no exception or suppression machinery — a team that departs from a recommendation records the decision (profile note or ADR) and the guardian reports it as visible accepted risk. Review output follows the [advisory report contract](../advisory-report.md).
-
-Tiers gate concerns, never tools:
-
-| Tier | Rigor floor |
-|---|---|
-| `prototype` | irreversibles only: no plaintext secrets in code, no cross-tenant access where tenancy exists, no auth bypass, reversible data decisions |
-| `production` | full correctness, security, and recovery concerns for enabled capabilities, in minimal viable form |
-| `enterprise` | adds immutable audit, supply-chain attestation, SCIM/deprovisioning depth, formal threat models, and eval/cost gates |
-
-Rules apply at tier `production` and above unless tagged `[tier: all]` (applies from prototype up) or `[tier: enterprise]`. Resolve decisions in this order: security/correctness; recovery; ownership; contracts; operability; delivery; optional optimization.
-
-- **FOUND-001 — Confirmed profile.** A project **MUST** commit a confirmed v4 `.vegastack/architecture.json` containing only confirmed facts: name, kind, tier, tenancy, hosting, and enabled capabilities (legacy names are accepted with a deprecation notice; versions live in lockfiles, never the profile). [tier: all]
-- **FOUND-003 — Honest outcomes.** The guardian **MUST NOT** represent unverified behavior as verified or accepted risk as recommended: findings follow the advisory evidence discipline, unverified claims are labeled, and a deliberate team decision the guardian disagrees with is reported as accepted risk with the reason — visibly, without suppression. [tier: all]
-- **FOUND-004 — Capability alignment.** The declared capability list **MUST** match project intent and repository evidence, and removing a capability **MUST** clean durable data, credentials, queues, and contracts. [tier: all]
-
-Prefer reproduced behavior over prose and official primary sources over secondary material. Apply pinned claims to the pinned baseline; current documentation describes current capability. Source drift requests scoped review.
-
-## Minimum viable architecture
-
-Never add a moving service without a named trigger. Every infra addition states the trigger it satisfies and the simpler option it replaces; every capability reference names its default and its escalation triggers. Libraries and standards with no operational cost are standing defaults when their capability applies: Better Auth, PostgreSQL, REST/OpenAPI, OCI, S3-compatible objects, OpenTelemetry, OAuth/OIDC, provider-neutral sandbox/model interfaces. Operational services are trigger-gated: OpenBao, Valkey, Kubernetes, WebSockets, regional cells, extracted services. Provider features must not become hidden correctness dependencies.
-
-## Ownership and portability
-
-Product-owned enabled capabilities are the default. Shared-managed and external-managed services are explicit ownership exceptions recorded in the profile notes with their contract; a consumer of a shared service does not contain the provider's source roots. The foundation excludes billing, pricing, and Stripe.
-
-Retired rule IDs are never reused: `FOUND-002` (exception governance) was retired in foundation 0.4.0 together with the enforcement machinery.

package/skill/arch-guardian/references/architecture/hosting-reliability.md

@@ -1,37 +0,0 @@
-# Hosting and reliability
-
-Apply a hosting profile only to declared production deployables. `none` is valid for a non-deployable shared package. EVE/jobs placement clauses activate only when those owned capabilities are enabled.
-
-## Exact placement profiles
-
-- **HOST-001 — Declared profile.** A deployable **MUST** match one exact profile below; provider capability does not silently change the selected baseline.
-- **HOST-002 — Self-hosted.** Starter production **MUST** use OCI deployables with Docker Compose documented as non-HA. It requires externalized backups, TLS, OpenBao bootstrap, monitoring, capacity, and explicit single-host failure handling.
-- **HOST-003 — Vercel.** The Vercel profile **MUST** use the `vercel-web-external-eve` baseline: Next runs on Vercel while EVE and pg-boss run in qualified external long-running Node/OCI placements with direct PostgreSQL access. AgentRun projection initially belongs to this trusted long-running plane. This is a VegaStack profile choice, not a claim that Vercel lacks other capabilities.
-- **HOST-004 — Cloudflare/OpenNext.** The OpenNext Worker owns only the Next control plane. EVE, Workflow packages, pg-boss workers, and background daemons **MUST NOT** enter its source or bundle. Tenant/auth paths use cache-disabled direct PostgreSQL semantics; `nodejs_compat` does not make the Worker a general Node process. [OPENNEXT-1202] [CF-WORKERS] [HYPERDRIVE]
-
-| Profile | Next | EVE and jobs | PostgreSQL/World | Required warning |
-|---|---|---|---|---|
-| self-hosted | Node OCI | Node OCI | direct PostgreSQL | Compose is non-HA |
-| Vercel | Vercel Next | external Node/OCI | external direct PostgreSQL | external runtime ownership |
-| Cloudflare/OpenNext | OpenNext Worker | external Node/OCI | external direct PostgreSQL | Worker Node subset; auth cache off |
-
-Profile changes require an ADR, deployment review, data/secret migration, contract and recovery tests, rollout, and rollback.
-
-## Reliability
-
-- **REL-001 — Measured objectives.** Each production profile **MUST** define measured objectives for its applicable enabled boundaries (such as API latency, admission age, EVE continuation, SSE freshness, dependency success or notification delivery), with RPO/RTO only where durable data and recovery requirements exist.
-- **REL-002 — Reproduced recovery.** Recovery plans **MUST** use encrypted PostgreSQL backups plus WAL/PITR, object versioning/replication where required, OpenBao recovery procedures, and independent restore verification. A successful backup job is not restore evidence.
-- **REL-003 — Regional ownership.** Add cells only for measured capacity, residency, or blast-radius needs. A workspace and its authoritative business/workflow state **MUST** have one home cell; moves use quiescence, copy, validation, cutover, and rollback.
-- **REL-004 — Incident ownership.** Teams **MUST** maintain owned incident documentation at their tier's depth: production — one runbook covering the top three realistic failures for enabled capabilities (typically database loss, workflow/job stalls, credential theft); enterprise — the full set including cross-tenant exposure, sandbox egress/escape, model data incidents, connector abuse, provider/cell loss, and deletion failure.
-
-| Failure | Expected recovery evidence |
-|---|---|
-| Next loss | retry/idempotency; durable state intact |
-| pg-boss crash | lease retry; same admission/effect key |
-| EVE crash | World resume/replay; effect reconciliation |
-| PostgreSQL loss | fail closed; PITR/failover within objectives |
-| sandbox crash | recreate from durable inputs; cleanup reconciliation |
-| dependency outage | policy-safe fallback or visible pause |
-| cell loss | home-cell routing and exercised recovery plan |
-
-Add Kubernetes only when HA, scale, placement, or operational requirements exceed Compose/managed profiles. Change workflow ownership only after the qualified EVE/Postgres World baseline fails a required capability and an ADR proves migration and rollback. PostgreSQL 18 is the candidate major-version horizon for these profiles; treat it as a qualification event, not a drop-in upgrade. <!-- source: POSTGRES-DOCS -->

package/skill/arch-guardian/references/architecture/identity-tenancy.md

@@ -1,37 +0,0 @@
-# Identity and tenancy
-
-Apply identity rules only to authenticated/delegated/service access that exists. Apply organization rules to multi-tenant workspace products. Apply `TEN-*` rules to shared-schema multi-tenancy; public, single-tenant and isolated-database projects do not acquire RLS requirements merely by using VegaStack.
-
-## Identity boundary
-
-- **AUTH-001 — Workspace boundary.** For authenticated multi-tenant products, Better Auth organization **MUST** be the workspace boundary. A client-supplied or session-cached active organization **MUST NOT** authorize access without current membership resolution. Projects MAY subdivide a workspace.
-- **AUTH-002 — Resource authorization.** `owner`, `admin`, and `member` are coarse membership roles; teams are grouping only. Application-owned typed resource policies and grants **MUST** be authoritative and default-deny. [BETTERAUTH-ORG]
-- **AUTH-003 — Browser sessions.** Browser authentication **MUST** use secure, HttpOnly, SameSite cookies. CSRF/origin checks **MUST NOT** be disabled; production origins **MUST** be exact HTTPS allowlists. Sensitive actions **MUST** revalidate the session and current membership against durable storage rather than trusting cookie cache. [tier: all] [BETTERAUTH-SESSIONS] [BETTERAUTH-SECURITY]
-- **AUTH-004 — Delegated clients.** Flutter, MCP, delegated applications, and third parties **MUST** use authorization code with S256 PKCE, discovery, explicit consent, audience/resource validation, refresh rotation, revocation, and introspection. Reject `require_pkce: false`; do not use the Bearer plugin as the mobile foundation. Verify that OAuth and OIDC discovery endpoints are reachable outside framework catch-all routes. [BETTERAUTH-OAUTH]
-- **AUTH-005 — Automation and services.** Workspace API keys **MUST** be organization-owned, hashed, scoped, expiring, rate-limited, and revocable. Internal service-to-service identity **MUST** be short-lived and audience-bound — OpenBao-issued identities with mTLS where the multi-service trigger is met, platform-issued identities otherwise. Neither identity may synthesize a browser session. [BETTERAUTH-APIKEY] [OPENBAO-DOCS]
-- **AUTH-006 — Enterprise provisioning.** SSO and SCIM connections **MUST** be organization-scoped. Production `defaultSCIM` and plaintext SCIM token storage are forbidden. Deprovisioning **MUST** revoke sessions, memberships, grants, API keys, connector access, and support elevation. [tier: enterprise] [BETTERAUTH-SSO] [BETTERAUTH-SCIM]
-- **AUTH-007 — Support elevation.** Support access **MUST** be visible, reason/ticket-bound, narrowly scoped, expiring, revocable, and immutable-audited. It **MUST NOT** impersonate a user or bypass normal RLS.
-
-## Tenant database boundary
-
-- **TEN-001 — Composite tenant keys.** Every tenant-owned primary, unique, and foreign-key relationship **MUST** include `workspace_id`; a globally unique object ID is not tenant isolation. [tier: all]
-- **TEN-002 — Forced RLS.** Every tenant table **MUST** enable and force PostgreSQL RLS with fail-closed `USING` and `WITH CHECK` coverage appropriate to each command. [tier: all] [POSTGRES-DOCS]
-- **TEN-003 — Trusted transaction context.** Request roles **MUST** be non-owner and lack `BYPASSRLS`. Trusted server code **MUST** establish workspace, subject, and support context using `SET LOCAL` or `set_config(..., true)` inside the same explicit transaction as protected queries. Clients and pooled session state **MUST NOT** set it. [tier: all]
-- **TEN-004 — Privileged and batch paths.** Bulk, export, background, support, and maintenance paths **MUST** preserve tenant context. A `SECURITY DEFINER` function **MUST** use a fixed safe `search_path`, revoke public execution, validate tenant inputs, and avoid an RLS-bypassing owner. [tier: all]
-
-```mermaid
-sequenceDiagram
-  participant API as Trusted API
-  participant Policy as Typed authorizer
-  participant DB as PostgreSQL transaction
-  API->>Policy: subject, workspace, action, resource
-  Policy-->>API: allow plus policy version
-  API->>DB: BEGIN and SET LOCAL context
-  API->>DB: query with workspace composite key
-  DB-->>API: RLS-filtered result
-  API->>DB: append audit and COMMIT
-```
-
-Use cache-disabled database paths for auth, session, permission, and RLS-sensitive reads. Hyperdrive transaction pooling resets session state and eligible cached reads do not provide authorization freshness. [HYPERDRIVE]
-
-Qualification includes applicable cross-workspace IDs, joins, subqueries, composite foreign keys, inserts/updates, exports, background jobs, migrations, pool reuse, support expiry, role ownership, `SECURITY DEFINER`, SCIM deprovisioning, and session revocation.

package/skill/arch-guardian/references/architecture/model-lifecycle.md

@@ -1,20 +0,0 @@
-# Model lifecycle
-
-Apply this reference only when external model providers are enabled or observed. It extends `MODEL-001` through `MODEL-003` with lifecycle, rollout, and pressure behavior; the provider-neutral adapter remains the enforcement point.
-
-Minimum viable form by tier — prototype: pin explicit model identifiers, nothing more. Production: pins plus deprecation watch and basic backpressure handling. Enterprise: the full regime including canary/cohort rollout and qualified fallback policy.
-
-- **MLIFE-001 — Explicit model pins.** Every route **MUST** pin an explicit model identifier. Floating aliases such as `latest` or provider-default snapshots are forbidden in production routes; alias resolution happens at review time, and the resolved identifier is what ships. [tier: all]
-- **MLIFE-002 — Deprecation watch.** The project **MUST** subscribe to deprecation and retirement notices for every pinned model and record, per model, the announced retirement date, the chosen successor, and a migration window that completes eval and cost qualification (`EVAL-002`, `COST-004`) before the provider deadline. A pinned model with a published retirement date and no successor plan is a critical finding, not a footnote.
-- **MLIFE-003 — Canary rollout.** Prompt+model behavior changes reaching production-tier users **MUST** roll out by canary or cohort: a bounded traffic slice, pre-declared comparison metrics (eval score, error rate, latency, cost), and automatic or one-step rollback to the prior pinned pair. Prototype and internal-only surfaces may ship directly. Cohort assignment respects tenant policy; a tenant is never split across behavior variants within one conversation.
-- **MLIFE-004 — Provider backpressure.** Provider rate limits and `429`/overload responses **MUST** be absorbed by the adapter with bounded adaptive backoff, per-tenant fairness, and admission shedding at the queue edge — reject or defer new work visibly rather than retrying into a saturated provider. Retries **MUST NOT** amplify load, and fallback routing under pressure obeys `MODEL-003` policy preservation.
-
-## Retirement flow
-
-`pinned → deprecation notice → successor selected → eval and cost qualification → canary → cohort ramp → old pin removed`. Each step records evidence; skipping straight from notice to swap is qualification debt. Where the provider offers a legacy alias during migration, treat it as a bridge with an end date, not a destination. The provider model catalogs and deprecation registries are the watch surface. [ANTHROPIC-MODELS] [OPENAI-MODELS] [GOOGLE-MODELS]
-
-## Fallback and admission
-
-Fallback order is part of route policy: same-policy alternates first, degraded-capability alternates only when the product declares the degradation acceptable, visible pause when nothing satisfies policy. Record which pin actually served each request — a fallback that served traffic for a week is a de facto primary and must be qualified as one.
-
-Admission shedding is an architecture concern, not an error handler: quotas per workspace and per feature decide who waits when capacity shrinks, and shed work surfaces as retryable, audited outcomes rather than silent loss. Measure provider error and latency baselines continuously so a deprecation-driven migration has a comparison target.

package/skill/arch-guardian/references/architecture/models-observability.md

@@ -1,23 +0,0 @@
-# Models and observability
-
-Apply model rules only when model routing is enabled or observed. Apply telemetry/audit rules to signals and audit surfaces the project actually emits.
-
-## Model routing
-
-- **MODEL-001 — Provider-neutral adapter.** Model calls **MUST** use a provider-neutral adapter that declares model capabilities, streaming, structured output, tool use, region, retention, key source, quota, timeout, and fallback policy.
-- **MODEL-002 — Key paths.** Platform keys stay in the trusted model service. Workspace BYOK **MUST** persist only as encrypted ciphertext/reference and be resolved just in time; agents and sandboxes receive neither key path.
-- **MODEL-003 — Policy-preserving fallback.** Fallback and caches **MUST NOT** weaken region, retention, key-source, data-class, or tenant policy. A blocked fallback pauses visibly rather than silently changing policy.
-
-Prefer Cloudflare AI Gateway behind the adapter; direct AI SDK providers and qualified self-hosted alternatives remain supported. Explicitly configure gateway logging/caching to the same privacy contract. [AI-GATEWAY] [AI-SDK-7]
-
-Record route decision, policy version, provider/model, key source, region, latency, token/usage estimate, cache/fallback state, approval link, and outcome—never the key. Low-retention/no-retention requests must fail closed when no route satisfies policy.
-
-## Telemetry and audit
-
-- **OBS-001 — Vendor-neutral telemetry.** Services **MUST** emit OpenTelemetry-compatible traces, metrics, and logs with W3C propagation and stable tenant-safe correlation. [OTEL-DOCS]
-- **OBS-002 — Metadata-only default.** Telemetry **MUST** default to metadata. Cookies, authorization headers, tokens, keys, prompts, restricted content, and unbounded tool output **MUST NOT** enter logs or traces.
-- **OBS-003 — Immutable audit.** Security and product audit events **MUST** be append-only, tenant-scoped, and access-controlled; tamper evidence, managed retention, and WORM export bind at enterprise tier.
-
-Run history MAY expose inputs/outputs allowed by data policy, steps, tool calls, approvals, model decisions, usage, errors, and replay lineage. Do not store hidden chain-of-thought; retain structured reasons, decisions, and evidence references.
-
-Define owners and alerts for API latency, admission age, EVE stalls, connector/model/sandbox failures, SSE freshness, notification delivery, audit pipeline health, and deletion backlog.