Execution Guardian

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:

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:

Composite Risk Calculation

composite_score = max(blast_radius, reversibility, confidence)

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:

Confidence Thresholds

---

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

---

Self-Healing Retry

When BLOCKING: NO and risk is LOW:

1. Apply the suggested FIX automatically 2. Re-run the failed gate 3. If pass → proceed 4. 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

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

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

Execution Guardian - Error Format Reference

Complete examples of the structured error format per operation type, plus the BLOCKING classification decision tree.

---

Error Format Template

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 by Operation Type

DATABASE_MIGRATION

ERROR: Migration revision abc123 lacks downgrade function
CAUSE: Alembic revision has no downgrade() — migration is irreversible
RISK:  HIGH — Schema change cannot be rolled back without manual intervention
FIX:   Add downgrade() function to abc123 revision with reverse operations
BLOCKING: YES

ERROR: Migration drops column 'contractor_notes' with existing data
CAUSE: DROP COLUMN on non-empty column causes permanent data loss
RISK:  HIGH — 2,847 rows affected; data is not recoverable
FIX:   Add data migration step to preserve values before dropping column
BLOCKING: YES

AUTH_CHANGE

ERROR: JWT_SECRET_KEY hardcoded in source file
CAUSE: Secret detected in apps/backend/src/auth/jwt.py line 14
RISK:  HIGH — Credential exposure if committed to version control
FIX:   Move to environment variable; reference via os.getenv("JWT_SECRET_KEY")
BLOCKING: YES

ERROR: Session invalidation strategy missing for secret rotation
CAUSE: JWT_SECRET_KEY change will invalidate all existing tokens with no graceful handling
RISK:  MEDIUM — All users will be force-logged-out simultaneously
FIX:   Implement dual-key validation period or gradual session expiry
BLOCKING: YES

API_CONTRACT_CHANGE

ERROR: Breaking change to /api/contractors response shape
CAUSE: Field 'availability' renamed to 'schedule' without frontend update
RISK:  MEDIUM — Frontend will render undefined for contractor availability
FIX:   Update Zod schema in apps/web/lib/api/ to match new field name
BLOCKING: YES

ERROR: New endpoint /api/analytics/trends missing documentation
CAUSE: Endpoint added without changelog entry or API docs update
RISK:  LOW — Functional but undocumented
FIX:   Add entry to docs/reference/ and update changelog
BLOCKING: NO

DESTRUCTIVE_FILE_OP

ERROR: Target files contain uncommitted changes
CAUSE: git status shows 3 modified files in deletion target
RISK:  HIGH — Uncommitted work will be permanently lost
FIX:   Commit or stash changes before proceeding: git stash push -m "pre-deletion backup"
BLOCKING: YES

DEPLOYMENT

ERROR: Test suite has 4 failures
CAUSE: uv run pytest returned exit code 1 with 4 FAILED tests
RISK:  HIGH — Deploying with known test failures risks production regression
FIX:   Resolve failing tests before deployment
BLOCKING: YES

ERROR: .env.production contains ANTHROPIC_API_KEY in build output
CAUSE: Secret leaked into deployable artifact
RISK:  HIGH — API key exposed in production build
FIX:   Remove from build output; use runtime environment injection instead
BLOCKING: YES

SECURITY_CHANGE

ERROR: CORS policy set to allow all origins (*)
CAUSE: Access-Control-Allow-Origin: * permits any domain
RISK:  MEDIUM — Enables cross-origin requests from malicious sites
FIX:   Restrict to specific origins: ["http://localhost:3000", "https://yourdomain.com"]
BLOCKING: YES

MULTI_LAYER_CHANGE

ERROR: Backend response model diverges from frontend Zod schema
CAUSE: UserResponse added 'role' field; Zod schema in apps/web/ does not include it
RISK:  MEDIUM — Frontend will silently drop the new field; no runtime error but data loss
FIX:   Add 'role' field to frontend Zod schema with appropriate type
BLOCKING: YES

DEPENDENCY_CHANGE

ERROR: Package 'lodash' has known prototype pollution vulnerability
CAUSE: pnpm audit reports CVE-2021-23337 in lodash@4.17.20
RISK:  LOW — Vulnerability requires specific usage pattern not present in codebase
FIX:   Upgrade to lodash@4.17.21+ or replace with native alternatives
BLOCKING: NO

---

BLOCKING Classification Decision Tree

Is the operation destructive or irreversible?
├── YES → BLOCKING: YES
└── NO
    ├── Does it affect auth, security, or payment?
    │   ├── YES → BLOCKING: YES
    │   └── NO
    │       ├── Does it break an existing contract (API, DB schema)?
    │       │   ├── YES → BLOCKING: YES
    │       │   └── NO
    │       │       ├── Is it documentation/advisory only?
    │       │       │   ├── YES → BLOCKING: NO
    │       │       │   └── NO → BLOCKING: YES (default to safe)

---

Severity Escalation

When multiple errors are detected for a single operation:

1. Report all errors in sequence 2. Overall BLOCKING = YES if any individual error is BLOCKING: YES 3. Overall RISK = highest individual risk level 4. FIX section lists all required fixes in priority order