mosaicstack/stack

Fork 0

Files

Hermes Agent 373e4558a3

ci/woodpecker/push/ci Pipeline failed

Details

ci/woodpecker/pr/ci Pipeline failed

Details

chore(framework): canonize Vault-as-SSOT + ESO-default secrets policy

Encodes operator-approved (Jason, 2026-05-22) secrets policy as binding
framework rules across all Mosaic agent sessions and projects.

Changes:
- STANDARDS.md: add "Secrets handling (HARD RULE)" subsection under
  Non-Negotiables — Vault as SSOT, ESO bridge as default, Direct-Vault
  opt-in only, forbidden ${VAR:-default} for required values, forbidden
  .env in prod, required startup schema validation
- VAULT-SECRETS.md: add four new sections — architecture decision matrix
  (ESO vs Direct-Vault), full ESO bridge worked example (Vault path +
  ExternalSecret + Deployment YAML + zod/pydantic/Go validators),
  Direct-Vault opt-in pattern (AppRole provisioning + ESO bootstrap
  for chicken-and-egg), and forbidden patterns CI lint targets
- BOOTSTRAP.md: add "Secrets Bootstrap" required subsection with
  checklist for new apps (Vault path, README docs, ExternalSecret,
  secretKeyRef, schema validator, Direct-Vault justification)

All duplicate file paths kept in sync (md5-equal pairs):
  guides/ <-> packages/mosaic/framework/guides/
  packages/mosaic/framework/defaults/STANDARDS.md (single copy in repo)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-22 11:58:27 -05:00

3.8 KiB

Raw Blame History

Mosaic Universal Agent Standards

This file is the canonical standards contract for agent sessions on this machine.

Master/slave model:

Master: ~/.config/mosaic (this framework)
Slave: each repo bootstrapped via mosaic-bootstrap-repo

Execution Model

Load this file first.
Load project-local AGENTS.md next.
Respect repository-specific tooling and workflows.
Use lifecycle scripts when available (scripts/agent/*.sh).
Use shared tools/guides from ~/.config/mosaic as canonical references.

Non-Negotiables

Data files are authoritative; generated views are derived artifacts.
Pull before edits when collaborating in shared repos.
Run validation checks before claiming completion.
Apply quality tools from ~/.config/mosaic/tools/ when relevant (review, QA, git workflow).
For project-level mechanical enforcement templates, use ~/.config/mosaic/tools/quality/ via ~/.config/mosaic/bin/mosaic-quality-apply.
For runtime-agnostic delegation/orchestration, use ~/.config/mosaic/tools/orchestrator-matrix/ with repo-local .mosaic/orchestrator/ state.
Avoid hardcoded secrets and token leakage in remotes/commits.
Do not perform destructive git/file actions without explicit instruction.
Browser automation (Playwright, Cypress, Puppeteer) MUST run in headless mode. Never launch a visible browser — it collides with the user's display and active session.

Secrets handling (HARD RULE)

Vault is the canonical source-of-truth for every secret in every environment. No exceptions.
For k8s workloads, the default read path is External Secrets Operator → k8s Secret → env var (secretKeyRef). The app reads standard env vars; no Vault client in app code.
Direct-Vault clients in application code are opt-in only, justified per-app by a documented dynamic-secrets requirement (e.g., DB rotation, AWS STS). Default to ESO. Document the justification in the project's README under "Secrets architecture".
${VAR:-default} fallback syntax in any deployment configuration (compose, k8s manifests, Helm values, env files committed to git) is forbidden for required values. Use ${VAR:?VAR is required} to fast-fail. Defaults are allowed only for true conveniences (e.g. ${PORT:-3000}) and MUST be tagged # safe-default: <reason> so a reviewer can confirm the intent.
.env files in production deployment paths are forbidden. .env.example and .env in local-dev paths are fine.
App startup MUST validate required secrets against a schema (zod / pydantic / equivalent) and exit non-zero on missing required values. Never run with defaulted weak fallbacks.
New apps: bootstrap checklist (see ~/.config/mosaic/guides/BOOTSTRAP.md) MUST include Vault path provisioning + ExternalSecret manifest + README declaring the Vault path and required keys.

Session Lifecycle Contract

Start: scripts/agent/session-start.sh
Priority scan: scripts/agent/critical.sh
End: scripts/agent/session-end.sh
Limitation logging helper: scripts/agent/log-limitation.sh "Title"

If a repo does not expose these scripts, run equivalent local workflow commands and document deviations.

Multi-Agent Safety

Coordinate through git pull/rebase discipline.
Do not auto-resolve data conflicts in shared state files.
Keep commits scoped to a single logical change set.

Prompting Contract

All runtime adapters should inject:

~/.config/mosaic/STANDARDS.md
project AGENTS.md

before task execution.

Runtime-compatible guides and tools are hosted at:

~/.config/mosaic/guides/
~/.config/mosaic/tools/
~/.config/mosaic/profiles/ (runtime-neutral domain/workflow/stack presets)
~/.config/mosaic/runtime/ (runtime-specific overlays)
~/.config/mosaic/skills-local/ (local private skills shared across runtimes)

3.8 KiB Raw Blame History