docs(guardrails): document the source-precedence ladder#151
Merged
Conversation
… config The doc previously said "Priority: FORGE_GUARDRAILS_DB env → guardrails.json → built-in defaults" in one line and called it done. That obscures three things operators reliably ask about: 1. DB-mode failure is *non-fatal* — connect/ping errors fall back to file mode with a warning, not a hard exit. Misconfigured URIs surface as silently-degraded posture unless someone is watching logs. 2. `guardrails.json` is still copied into the image even when DB mode is the runtime choice. Toggling FORGE_GUARDRAILS_DB at deploy time flips the mode without a rebuild — easy to forget when shipping "DB-only" deployments. 3. There's a fifth row (NoopGuardrailChecker) that fires when engine construction errors after the source was already picked. This is the "everything passes through" failure mode and was completely undocumented. Replaces the one-liner with a five-row table mapping each trigger to its outcome and the fate of lower-priority sources. Adds a follow-up notes block covering the bypass semantics, the FORGE_ORG_ID requirement, the cfg.GuardrailsPath scope, and the divergent audit sinks across modes. Source: forge-cli/runtime/guardrails_loader.go. No code changes — pure documentation.
…erence
Adds the missing pieces to the guardrails reference doc:
1. Library link in the opening paragraph — names github.com/initializ/
guardrails, pins the version (v0.12.0 from forge-cli/go.mod), and
points at models/config.go as the authoritative type definition.
Operators reading this doc now know where the schema lives instead
of having to grep the codebase.
2. A new "Full guardrails.json Schema" subsection enumerating all ten
top-level blocks supported by models.StructuredGuardrails — five of
them (moderation, urlFilter, approvalGates, nsfwText, hallucination,
skillConstraints) were previously undocumented even though the
library accepts them and they round-trip into MongoDB's AgentConfig
in DB mode.
3. Per-block JSON snippets + field-level tables covering type,
purpose, and value vocabulary. Reflects the actual struct tags in
the pinned library version.
4. A compatibility notes block calling out:
- what forge init bootstraps vs. what's accepted but not generated
- omitted-key == disabled semantics
- camelCase + bson tags round-tripping between file mode and DB
mode without translation
Reinforces that both file-mode guardrails.json and DB-mode AgentConfig
share one schema, so an operator who learns one knows the other.
Stacks on the precedence-table commit (634997d) in the same docs PR.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Extends `docs/security/guardrails.md` § Architecture with a five-row precedence table mapping each config-source trigger to its outcome and what happens to lower-priority sources. Source-truth: `forge-cli/runtime/guardrails_loader.go:BuildGuardrailChecker`.
Why
The previous one-line summary (`Priority: FORGE_GUARDRAILS_DB env → guardrails.json → built-in defaults`) obscures three things operators reliably ask about:
Changes
Test plan