backend-guardrails

Backend Guardrails Adapter

Prerequisite: guardrails-coding-agent must be installed.

Invocation Sequence

Pre-work gates

1. Detect operationType Scan the current task context:

• If task involves SQL DDL files or EF Core migration classes → operationType: migration
• Otherwise → operationType: none

2. Invoke input-validation with:

agentFamily: "backend-coding-agent"
allowedActions: ["code", "refactor", "review", "test"]
scopedPaths: ["src/", "tests/", "lib/"]
blockedPaths: [] (use config override if set)

3. Invoke budget-monitor with:

agentFamily: "backend-coding-agent"
userStoryId: <from config or prompt>
accumulatedCost: <read from .guardrails-costs.jsonl rollup>

4. Invoke policy-enforcement with:

agentFamily: "backend-coding-agent"
resolvedLanguage: <from config-resolver>
resolvedFramework: <from config-resolver>
allowedAgents: <from policy.allowedAgents>
lspStatus: <from LSP startup result>

5. Invoke harm-prevention with:

agentFamily: "backend-coding-agent"
languagePatternSet: <language-specific patterns — see below>
patternOverrides:
  go-unsafe-unguarded: { requiredComment: "// guardrails:unsafe-approved", severity: P0 }
  csharp-reflection-unguarded: { requiredComment: "// guardrails:reflection-approved", severity: P1 }

Language pattern resolution:

Language	Applicable pattern IDs from defaults/forbidden-patterns.md
Go	go-unsafe-unguarded, path-traversal
C#	csharp-reflection-unguarded, process-start-user-input, path-traversal
Java	exec-with-input, path-traversal
Node.js	eval-with-input, exec-with-input, dangerous-inner-html, prototype-pollution, path-traversal

Pass the resolved language's pattern IDs as the languagePatternSet argument.

6. If operationType is migration: invoke idempotency-guard with:

operationType: "migration"
phase: "pre"
migrationsDir: <resolved from config or default: "db/migrations/">

7. Invoke artifact-validator (pre-write phase) with:

artifactPath: <path of file about to be written>
artifactContent: <content to be written>
language: <resolved from config-resolver>
scanDirs: <from artifactValidation.scanDirs config, default: ["src/", "lib/", "controllers/", "services/", "repositories/", "models/", "middleware/", "tests/"]>
phase: "pre-write"

This gate fires BEFORE every Write or Edit to detect duplicate backend artifacts. If artifact-validator returns BLOCK: halt and report to human. If artifact-validator returns HUMAN_REVIEW: surface the ambiguity to the human and wait for confirmation before proceeding. If the human denies: abort the write and log the decision in the audit trail.

Agent does its work

Post-write artifact validation:

After the agent writes all artifacts, invoke artifact-validator (post-work phase) with:

artifactPath: <list of all files created/modified during this session>
language: <resolved from config-resolver>
scanDirs: <from config>
phase: "post-work"

If any BLOCK-level finding: halt and surface to human before proceeding to post-work gates.

Post-work gates

8. Resolve tools by language:

Language	lintTool	coverageTool
Go	golangci-lint ./...	go test -cover ./...
C#	dotnet format --verify-no-changes	dotnet test --collect:"XPlat Code Coverage"
Java	checkstyle -c /google_checks.xml src/	mvn jacoco:report
Node.js	eslint src/	jest --coverage

9. Invoke output-validation with:

agentFamily: "backend-coding-agent"
lintTool: <resolved above>
coverageTool: <resolved above>
coverageReportPath: null (use tool default)

10. If operationType != none: invoke idempotency-guard with:

operationType: <resolved>
phase: "post"

11. Invoke drift-detection with:

agentFamily: "backend-coding-agent"
pinnedVersions: <from drift.pinnedVersions>
driftBaselineRef: <from drift.driftBaselineRef, default: "main">
driftTrigger: "session-start"

12. Invoke cost-tracker with:

userStoryId: <from config or prompt>
sessionTokensUsed: <estimated from session context>
modelRateKey: "claude-sonnet-4-6"

13. Invoke audit-trail with:

gateResults: <all gate outcomes from steps 2-12>
agentFamily: "backend-coding-agent"
sessionId: <generate: "backend-coding-agent-<timestamp>">
userStoryId: <from config or prompt>

14. Invoke artifact-validator (commit phase) with:

artifactPath: <list of all files staged for commit>
language: <resolved from config-resolver>
scanDirs: <full repository scan>
phase: "commit"

This final pass re-validates all staged artifacts against the full repo to catch duplicates introduced outside the current session. If any BLOCK: prevent the commit and surface to human.

15. If any gate returned BLOCK or WARN: invoke error-escalation with:

gateResults: <all gate outcomes>
agentFamily: "backend-coding-agent"
sessionId: <from step 13>

16. Invoke memory-writer (final post-work step) with:

agentFamily: "backend-coding-agent"
sessionId: <from step 13>
userStoryId: <from config or prompt>
ticketSummary: <short title from the story/task, if available>
filesModified: <list of repo-relative paths touched this session>
patternsChosen:
  language: <resolved from config-resolver>
  framework: <resolved from config-resolver>
  languageVersion: <resolved from config-resolver>
  designPatterns: <list of patterns actually used, e.g. ["service-layer", "repository"]>
teamConventions: <non-obvious conventions observed from guidelines-ingestion>
lessonsLearned: <problems hit this session and how they were resolved — empty list when none>
outcome: <success | partial | blocked | failed>

Memory-writer is best-effort telemetry. Never block the session on a memory-write failure.