Pre-execution governance with dynamic validation gates, risk/confidence scoring, and structured error format. Activates before destructive, multi-layer, or security-impacting operations to assess safety.
Pre-execution governance with dynamic validation gates, risk/confidence scoring, and structured error format. Activates before destructive, multi-layer, or security-impacting operations to assess safety.
Dynamic validation gates and risk assessment for operations that could harm system integrity. Evaluates blast radius, reversibility, and confidence before allowing execution to proceed.
Description
Provides a pre-execution safety layer that auto-detects operation types, generates prerequisite validation gates, scores risk and confidence, and produces structured error output when operations are blocked. Complements the Council of Logic (code quality) with operation safety assessment.
For each detected operation type, generate prerequisite gates. Gates are checks that must pass before execution proceeds.
DATABASE_MIGRATION Gates
GATE: Backup exists or migration is reversible
CHECK: Verify downgrade() function exists in Alembic revision
BLOCKING: YES
GATE: No data loss in migration
CHECK: Scan for DROP COLUMN, DROP TABLE, ALTER TYPE without data preservation
BLOCKING: YES
GATE: Migration tested locally
CHECK: uv run alembic upgrade head (on local database)
BLOCKING: YES
AUTH_CHANGE Gates
GATE: No secret exposure in code
CHECK: Grep for hardcoded secrets, JWT keys, API keys in diff
BLOCKING: YES
GATE: Existing sessions handled
CHECK: Verify session invalidation strategy for JWT secret rotation
BLOCKING: YES
GATE: Auth tests pass
CHECK: uv run pytest tests/test_auth.py
BLOCKING: YES
API_CONTRACT_CHANGE Gates
GATE: Breaking change documented
CHECK: Verify changelog entry or API version bump
BLOCKING: NO (warning only)
GATE: Frontend contract updated
CHECK: Verify corresponding Zod schema change in apps/web/
BLOCKING: YES
GATE: API tests pass
CHECK: uv run pytest tests/test_api_*.py
BLOCKING: YES
DESTRUCTIVE_FILE_OP Gates
GATE: Files are not uncommitted work
CHECK: git status — verify target files are committed or backed up
BLOCKING: YES
GATE: No shared resources affected
CHECK: Verify files are not imported/referenced by other modules
BLOCKING: YES
DEPLOYMENT Gates
GATE: All tests pass
CHECK: pnpm turbo run test
BLOCKING: YES
GATE: Type checks pass
CHECK: pnpm turbo run type-check
BLOCKING: YES
GATE: No secrets in build output
CHECK: Scan build artifacts for .env patterns
BLOCKING: YES
SECURITY_CHANGE Gates
GATE: Change follows OWASP guidelines
CHECK: Reference input-sanitisation or csrf-protection skill
BLOCKING: NO (advisory)
GATE: Security tests pass
CHECK: uv run pytest tests/ -k "security or auth"
BLOCKING: YES
MULTI_LAYER_CHANGE Gates
GATE: API contract consistency
CHECK: Backend response models match frontend Zod schemas
BLOCKING: YES
GATE: Cross-layer tests pass
CHECK: pnpm turbo run test (full suite)
BLOCKING: YES
DEPENDENCY_CHANGE Gates
GATE: No known vulnerabilities
CHECK: pnpm audit / uv pip audit
BLOCKING: NO (warning for non-critical)
GATE: Peer dependency compatibility
CHECK: pnpm install --dry-run succeeds
BLOCKING: YES
CONFIG_CHANGE Gates
GATE: Config syntax valid
CHECK: Validate JSON/TOML/YAML syntax
BLOCKING: YES
GATE: Environment variables documented
CHECK: New variables added to .env.example
BLOCKING: NO (warning)
Confidence is scored 0-100% based on four factors:
Factor
Weight
High Confidence
Low Confidence
Pattern Novelty
30%
Well-known pattern used elsewhere in codebase
First-time pattern, no precedent
Test Coverage
30%
Relevant tests exist and pass
No tests cover this path
Domain Complexity
20%
Simple CRUD, config change
Auth, payment, distributed state
Change Scope
20%
Single file, < 50 lines
5+ files, 200+ lines
Confidence Thresholds
Range
Label
Action
80-100%
High
Proceed with standard gates
50-79%
Moderate
Require explicit approval
0-49%
Low
Recommend spike/prototype first, or request additional review
Structured Error Format
When the Guardian blocks an operation, output uses this format. This is distinct from error-taxonomy (which handles runtime API errors). Guardian errors are governance-level blocking decisions.
ERROR: {What failed or was blocked}
CAUSE: {Why the gate failed or risk is too high}
RISK: {LOW | MEDIUM | HIGH} — {one-line risk summary}
FIX: {Specific action to resolve the block}
BLOCKING: {YES | NO}
Examples
See references/error-format.md for complete examples per operation type.
BLOCKING Classification
BLOCKING
Meaning
When Used
YES
Operation cannot proceed until resolved
Data loss risk, security vulnerability, test failure
NO
Warning only — operation may proceed
Documentation missing, advisory best practice
Self-Healing Retry
When BLOCKING: NO and risk is LOW:
Apply the suggested FIX automatically
Re-run the failed gate
If pass → proceed
If fail again → escalate to BLOCKING: YES
Self-healing is never applied to:
BLOCKING: YES gates
MEDIUM or HIGH risk operations
Security-related gates
Database migration gates
Integration Points
Council of Logic
Council Member
Feeds Into
How
Turing (complexity)
Confidence scoring
High complexity = lower confidence
Von Neumann (architecture)
Blast radius assessment
Multi-service = higher blast radius
Shannon (compression)
Guardian output format
Structured, compressed error format
Boundary: Council validates code quality; Execution Guardian validates operation safety.
Genesis Orchestrator
Phase boundaries trigger gate re-evaluation
Guardian respects phase-locked execution (does not skip ahead)
Section completion gates align with Guardian's deployment gates
Verification Agent
LOW risk → standard verification
MEDIUM risk → verification + regression tests
HIGH risk → comprehensive verification + manual review recommendation
Execution Modes
EXPLORATION: Guardian off
BUILD: Standard gates, approval for MEDIUM+
SCALE: Full gates, rollback plans required for MEDIUM+
STRATEGY: Guardian off
Anti-Patterns
Pattern
Problem
Correct Approach
Gating every file edit
Over-governance, kills momentum
Only gate destructive/multi-layer/security ops
Skipping gates because "it's just a small change"
Small changes to auth/security can be catastrophic
Gate based on operation type, not change size
Blocking on advisory warnings in BUILD mode
Momentum loss
Advisory = BLOCKING: NO, proceed with warning
Applying self-healing to security gates
Could mask real vulnerabilities
Self-healing only for LOW risk, non-security gates
Generating rollback plans for LOW risk ops
Token waste, over-engineering
Rollback plans for HIGH risk only (MEDIUM in SCALE mode)
Checklist
Operation type correctly auto-detected
Prerequisite gates generated for all detected types
Risk scored across blast radius, reversibility, and confidence
Composite risk level drives appropriate response
Structured error format used for all blocks (ERROR / CAUSE / RISK / FIX / BLOCKING)
Self-healing only applied to BLOCKING: NO + LOW risk
Council of Logic feeds into confidence and blast radius
Mode-appropriate governance (BUILD vs SCALE intensity)
