Scope Fences That Catch When Agent Code Drifts Beyond Intent

·https://github.com/Kevandrew/sophia
repogoaicliagentsagent-loopsscope-verificationcode-generation

off-limits declarations + post-build drift detection map to the agent loop reviewer/judge gate — automated scope verification before code merges

Sophia is a Go CLI that sits between a prompt and the code an AI agent writes. You describe what you want changed. Before anything gets built, Sophia generates a change request — a structured record of what’s changing, what’s off-limits, what success looks like, and how to undo it. The agent builds against that contract. Post-build, Sophia runs validation to check whether the code stayed within the declared scope. If the AI touched files it wasn’t supposed to, you see exactly where it drifted.

The interesting pattern here is off-limits declarations as first-class objects. Most agent coding setups define what should happen — acceptance criteria, task descriptions, story requirements. Sophia flips that and also declares what shouldn’t happen. “Only touch the frontend. Don’t break the existing light theme.” That negative constraint gets encoded into the change request, and the post-build validation checks it mechanically. No human has to eyeball a diff to catch scope creep.

The change request breaks down into tasks with individual success criteria, and each task carries its own scope boundaries. Sophia validates after each task, not just at the end. The whole thing ships as an agent skill — drop it into your agent’s skill directory and it hooks into the normal conversation flow. The CLI underneath (sophia cr create, sophia cr validate) gives you direct control when you want it, but the skill layer means most interactions happen through natural language. There’s also a collaboration model using portable CR bundles and patches for sharing change requests across environments without needing a central server.

The undo plan baked into every change request is a detail worth noting. Before a line of code ships, there’s already a recorded path back. That’s the kind of thing you only appreciate after you’ve been burned by an agent refactor that left the codebase in an unrecoverable state at 2am.

Key Ideas

  • Off-limits declarations — explicitly declaring what the AI cannot touch, not just what it should build, encoded as structured scope constraints in the change request
  • Post-build drift detection — automated validation that code changes stayed within declared scope boundaries, catching files or modules the agent wasn’t authorized to modify
  • Undo plans as first-class artifacts — every change request includes a rollback path recorded before implementation begins
  • Task-level scope fencing — change requests decompose into tasks, each with individual success criteria and scope constraints, validated independently
  • Agent skill distribution — ships as a skill file that agents load contextually rather than requiring explicit CLI invocation for every operation
  • Portable CR bundles — change requests export as canonical bundles (sophia.cr_bundle.v1) for sharing without centralized infrastructure, supporting JSON, YAML, and NDJSON formats
  • Intent as the artifact of record — the structured change request becomes the reviewable object instead of the diff itself, shifting code review from “what does this look like” to “did it do what it was supposed to”

Links

← All discoveries