Skip to main content

Operations

Documentation Map​

Operations

This page is the operational entrypoint for runtime checks, deployment-adjacent verification, and recovery-oriented fast paths.

Tool / Contract Summary​

  • Runtime/contract behavior is defined in compose.yaml, config/**, and verifier scripts under scripts/**.
  • Feature-to-test mapping is canonical in MODULE_FEATURES.md (docs/MODULE_FEATURES.md).
  • Backlog and issue evidence progression is tracked in AUTONOMOUS_BACKLOG.md (docs/AUTONOMOUS_BACKLOG.md).

Current Verified State​

  • Repo validation surfaces are implemented and runnable from this repository.
  • Live verification paths exist for guardrails, OIDC bridge behavior, and contract consumers.
  • External-owner runtime dependencies remain external and must not be replaced with local shadow logic.

Quick Verify Paths​

Repo-fast:

python scripts/validate-identity-claim-vocabulary.py --contract config/identity/claim-vocabulary.v2.yaml
python scripts/validate-stackwide-claim-session-core.py --contract config/identity/stackwide-claim-session-core.v1.yaml
python scripts/validate-admitted-surface-client-contracts.py --admitted-surfaces config/clients/admitted-surfaces.v1.yaml
python scripts/verify-runtime-materialization-drift.py
python -m unittest tests.test_validate_stackwide_claim_session_core tests.test_validate_admitted_surface_client_contracts

Runtime guardrails:

python scripts/verify-runtime-guardrails-v1.py
python scripts/verify-runtime-guardrails-v1.py --live-host <host> --ssh-user <user> --remote-repo-path <path>
python scripts/verify-runtime-materialization-drift.py --live-host <host> --ssh-user <user> --remote-repo-path <path>

Bridge/runtime checks:

python scripts/validate-plane-oidc-runtime.py --base-url <plane-url> --insecure
python scripts/validate-loom-oidc-runtime.py --base-url <loom-url> --insecure

Readiness / Drift / Monitoring​

  • Contract/readiness checks are fail-closed where upstream truth is required.
  • Drift and stale-revision posture is validated via dedicated scripts.
  • Runtime materialization must be compared across repo truth, active compose config, container env, and app readback instead of trusting only one layer.
  • Operational evidence should be bounded (timeouts, limited log windows, no unbounded followers).

Recovery and Fail-Closed Notes​

  • Use bounded diagnostics only; avoid indefinite streams and high-pressure loops.
  • Re-runs must be idempotent; verify a second execution path explicitly.
  • On missing or contradictory upstream truth, preserve fail-closed behavior instead of local fallback authoring.
  • runbooks/BOOTSTRAP.md (docs/runbooks/BOOTSTRAP.md)
  • runbooks/BACKUP_RESTORE.md (docs/runbooks/BACKUP_RESTORE.md)
  • runbooks/SECRET_ROTATION.md (docs/runbooks/SECRET_ROTATION.md)
  • HOST_DOCKER_LOG_GUARDRAILS.md (docs/HOST_DOCKER_LOG_GUARDRAILS.md)

License: AGPLv3
Project: https://helpifyr.com