@vegastack/skills 0.5.0 → 0.7.0

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

@@ -1,40 +0,0 @@
-# Profile and governance
-
-The v4 profile is slim advisor memory — roughly a dozen lines of confirmed facts. `capabilities` is authoritative intent; repository detection is evidence for drift, never a reason to silently enable anything. Versions are read from lockfiles and manifests at advice time and are never duplicated into the profile.
-
-| Field | Meaning |
-|---|---|
-| `project.tier` | `prototype` / `production` / `enterprise` — decides which concerns apply (see foundation) |
-| `project.kind`, `tenancy` | confirmed project facts |
-| `hosting` | production hosting target (`none` for a non-deployable package) |
-| `capabilities` | enabled list: `web`, `flutter`, `agents`, `jobs`, `sandbox`, `connectors`, `knowledge`, `models`, `realtime`, `notifications`, `enterprise-identity` |
-| `notes` | free-form confirmed facts and recorded deviations |
-
-## Tier declaration
-
-Choosing the tier is a deliberate product decision, not a guess: prototype means the team accepts that only irreversibles are guarded; production means real users depend on it; enterprise means compliance-grade posture. Raising the tier is a review event — the guardian re-reviews enabled capabilities against the new floor and reports the gap as `production-gate`/`enterprise-gate` findings, not failures.
-
-## Capability activation
-
-Apply rules only when a capability is enabled in the profile or observed in the repository, at or below the declared tier. Key implications:
-
-- Flutter activates delegated OAuth/PKCE and generated-client rules.
-- Agents activate durable-execution ownership rules; at prototype tier a simpler loop is acceptable with a named migration path (see durable execution).
-- Untrusted execution activates the sandbox boundary.
-- Shared-schema multi-tenancy activates `TEN-*` at every tier.
-- Production secrets activate secret-custody guidance — the mechanism is tier- and trigger-dependent (see security and privacy), never automatically OpenBao.
-- Removing a capability requires a cleanup/migration plan for durable data, credentials, queues, and contracts.
-
-## Deviations
-
-There is no exception or suppression machinery. When the team deliberately departs from a recommendation:
-
-1. Record it — one line in `notes` for small departures; an ADR ([template](../assets/adr-template.md)) for consequential ones (owner, decision, revisit trigger).
-2. The guardian keeps reporting it in reviews as `accepted risk — guardian recommends revisiting`, with the reason. Recording a decision makes it visible and deliberate; it never silences the advisor and nothing gates on it.
-
-## Governance operations
-
-- Drift PRs from the automated source refresh are reviewed by whoever merges them.
-- Source staleness thresholds are a minimum of 14 days, aligned to the weekly automated refresh.
-- Profiles may pin `foundationVersion` (currently `0.4.0`); it is decoupled from the installer npm package version, so installer upgrades never change a project's pinned foundation.
-- Full qualification matrices (e.g. `DUR-007`) are required before the production tier, not before every merge; interim reviews record the gap under `notVerified`.

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

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

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

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

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

@@ -1,47 +0,0 @@
-# Refresh contract — arch-guardian
-
-Instructions for the scheduled refresh agent (and any human running a manual refresh). This file, together with `sources.json`, is the complete freshness contract for this skill.
-
-## What this skill claims
-
-- **Durable rules** (`references/architecture/*.md`, `references/*.md|json`): versionless principles. The refresh agent NEVER edits these. If a source change invalidates a durable rule, open an issue titled `drift: <rule-id>` quoting the evidence — do not edit.
-- **Mechanism-coupled claims**: sentences marked `<!-- source: SOURCE-ID -->` inside references. Durable intent expressed through vendor-named mechanisms (e.g. Better Auth option names, sandbox egress API, MCP negotiation). The agent may propose edits to these marked sentences ONLY, in the same PR as the registry update that evidences the change.
-- **Volatile layer** (the only files the agent edits freely):
-  - `refresh/sources.json` — the source registry and publish-time staleness snapshot (checksums, versions, retrieval times).
-  - `references/foundation-compatibility.json` — pinned baselines and the criticalSources mirror.
-
-## How to refresh
-
-1. **Deterministic pass first** (no LLM judgment):
-   `node scripts/refresh-evidence.mjs --registry refresh/sources.json`
-   drift/version-drift/stale/unavailable results are the work-list. Exit 1 with a critical entry means fail-closed: the run must not be silently skipped. The same pass also:
-   - queries OSV.dev for every pinned npm/PyPI package (`advisories` in the report; an advisory against a critical source's pin fails closed — the remediation is a human pin-bump decision, never silence);
-   - warns when a `reviewBy` date in `references/foundation-compatibility.json` has passed (`reviewOverdue`) — the baseline-adoption decision is overdue, and the warning repeats every run until a human makes it.
-2. **Accept verified changes** in the same code path:
-   `node scripts/refresh-evidence.mjs --registry refresh/sources.json --accept-baselines`
-   This writes registry, cache, and drift report together — never hand-edit checksums, versions, or timestamps; they must always come from a run.
-3. **Semantic verification** only for sources the deterministic pass flagged: read the changed source (WebFetch the registry URLs), decide whether any `<!-- source: X -->` marked sentence or compatibility pin is now wrong, and propose the minimal edit.
-4. **One standing refresh PR**, branch `refresh/weekly`, force-updated on every run (never stacked duplicates; the weekly workflow .github/workflows/refresh.yml maintains it). PR body lists: each changed source, old→new version/checksum, links to the evidence, and which marked sentences changed and why.
-5. Changes to durable rules, scripts, SKILL.md, assets, or tests are out of scope for a refresh PR — CI enforces this (refresh-guard workflow).
-
-## Cadence and thresholds
-
-Weekly scheduled run. Every `thresholdDays` in `sources.json` is ≥ 14 (2× cadence) so one missed run never breaches a threshold. Sources that would genuinely need faster tracking get a daily deterministic-only version check, not a lower threshold.
-
-## What counts as drift worth a PR
-
-- A pinned package/spec version changed (npm/pypi detection) → update `currentVersion`; if the supported baseline should move, that is a **separate human decision**, flagged in the PR body, never auto-applied to `foundation-compatibility.json` families.
-- A doc page's text-scope checksum changed → read the page; if the mechanism a marked sentence names changed, propose the sentence edit; if it is editorial churn, accept the baseline silently. Known per-request-churn sources (Google properties: `FCM-DOCS`, `GOOGLE-MODELS`) drift on nearly every fetch — their checksum drift alone is never a semantic signal; rely on their version/manual review instead.
-- A critical source is unavailable or a redirect leaves the approved host set → investigate immediately; host changes require a deliberate `approvedHosts` update in `scripts/refresh-evidence.mjs` (out of refresh-PR scope — open an issue).
-- An OSV advisory against a pinned package → propose the pin bump (with its qualification implications) in the PR body; never drop the advisory from the report.
-
-## Research index
-
-Registry entries carry an optional `llms` URL (the vendor's published `llms.txt`) alongside `docsIndex`. Agents answering questions that need current detail beyond a pinned claim should fetch the source's `llms` or `docsIndex` URL (or use an available docs MCP) — the registry doubles as the live research index, not just freshness metadata.
-
-## Never
-
-- Never edit rule IDs, MUST/SHOULD wording, or unmarked sentences.
-- Never expire, edit, or reference project ADRs — drift requests review; it never silently expires an ADR.
-- Never hand-write checksum/version/timestamp values.
-- Never archive third-party documentation bodies in this repo (claim metadata, URLs, hashes, and concise excerpts only).