Execution Guardian - Pre-Execution Governance

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.

When to Apply

Positive Triggers

• Destructive operations: Database migrations, file deletions, git reset , DROP TABLE , rm -rf

• Multi-layer changes: Modifications spanning frontend + backend + database in a single operation

• Auth/security changes: JWT secret rotation, RBAC permission changes, CORS policy updates, OAuth config

• Payment/billing changes: Pricing logic, subscription tiers, billing calculations

• API contract changes: Breaking changes to endpoint signatures, response shapes, error codes

• Deployment operations: Production deployments, infrastructure changes, environment variable updates

• Data migrations: Schema changes with existing data, column renames, type changes

• User mentions: "risk", "safe to proceed", "prerequisite", "validation gate", "confidence"

Negative Triggers (Delegate to Other Systems)

• Code quality review → council-of-logic

• Phase sequencing and workflow → genesis-orchestrator

• Architecture drift or dead code → system-supervisor

• Runtime error handling → error-taxonomy

• Exploration or read-only operations → No governance needed (EXPLORATION mode)

• Pure strategy/planning → No gates needed (STRATEGY mode)

Dynamic Validation Gates

Operation Type Auto-Detection

Scan the proposed operation and classify it into one or more operation types:

Operation Type Detection Signals Default Risk

DATABASE_MIGRATION

Alembic revision, ALTER TABLE , DROP , schema changes HIGH

AUTH_CHANGE

JWT config, RBAC rules, password hashing, session management HIGH

API_CONTRACT_CHANGE

Endpoint signature change, response model change, status code change MEDIUM

DEPLOYMENT

Docker push, vercel deploy , environment variable changes HIGH

DESTRUCTIVE_FILE_OP

rm -rf , git reset --hard , git clean -f , file overwrites HIGH

SECURITY_CHANGE

CORS policy, CSP headers, rate limit config, secret rotation HIGH

MULTI_LAYER_CHANGE

Changes in 2+ of: apps/web/ , apps/backend/ , scripts/ , docker-compose.yml

MEDIUM

DEPENDENCY_CHANGE

pnpm add , uv add , major version bumps, removing packages LOW

CONFIG_CHANGE

next.config , pyproject.toml , tsconfig.json , .env files LOW

Gate Generation

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)

Risk Scoring Engine

Three Dimensions

Each operation is scored across three dimensions:

Dimension LOW (1) MEDIUM (2) HIGH (3)

Blast Radius Single file/function Single service/layer Multiple services or shared infrastructure

Reversibility Easily undone (git revert, config rollback) Requires manual steps (data restore, migration rollback) Irreversible or extremely costly to reverse

Confidence Well-understood pattern, high test coverage Partially tested, some unknowns Novel pattern, low coverage, complex domain

Composite Risk Calculation

composite_score = max(blast_radius, reversibility, confidence)

Composite Score Risk Level Required Response

1 LOW Proceed. Log the operation.

2 MEDIUM Require user approval before execution. State the risk clearly.

3 HIGH Mandatory review. Require rollback plan. Block until approval received.

Risk-Appropriate Responses

LOW Risk:

[GUARDIAN: LOW RISK] Proceeding with {operation}. Gates passed: {list}. No rollback plan required.

MEDIUM Risk:

[GUARDIAN: MEDIUM RISK] {operation} requires approval. Blast radius: {assessment} Reversibility: {assessment} Confidence: {assessment} Approval required before proceeding.

HIGH Risk:

[GUARDIAN: HIGH RISK] {operation} blocked pending review. Blast radius: {assessment} Reversibility: {assessment} Confidence: {assessment}

Rollback Plan:

1. {step 1}
2. {step 2}
3. {step 3}

Approval required. Respond with "proceed" to continue.

Confidence Scoring

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)

• Rollback plan present for HIGH risk operations

Response Format

[AGENT_ACTIVATED]: Execution Guardian [MODE]: {EXPLORATION | BUILD | SCALE | STRATEGY} [OPERATION]: {detected operation type(s)} [RISK]: {LOW | MEDIUM | HIGH} [STATUS]: {gates_passed | approval_required | blocked}

{gate results, risk assessment, or structured error}

[NEXT_ACTION]: {proceed | await approval | apply fix | escalate}

Australian Localisation (en-AU)

• Date Format: DD/MM/YYYY

• Currency: AUD ($)

• Spelling: colour, behaviour, optimisation, analyse, centre, authorisation

• Tone: Direct, professional — state risks clearly without hedging