BoundedRun

Governed AI execution that turns software objectives into repository-scoped Codex work packages with risk gates, deterministic validation, stored evidence, and protected-action blocking.

Comment

Inspiration

AI coding tools can generate changes quickly, but trustworthy project execution requires more than code generation. A useful system must understand the objective, classify risk before acting, remain inside explicit boundaries, validate the result, preserve evidence, and stop safely when a protected action is requested.

BoundedRun was created to demonstrate that controlled middle ground: meaningful AI-assisted execution without unrestricted autonomy.

What it does

BoundedRun turns a software objective into a governed, auditable planning and validation flow.

It:

  1. Accepts and normalizes the objective.
  2. Classifies it as safe, review, or protected before planning.
  3. Uses GPT-5.6 through the OpenAI Responses API under a strict structured-output contract when an API key is available.
  4. Uses a visible deterministic fallback when GPT-5.6 is unavailable, disabled, or returns an invalid response.
  5. Selects only one of three allow-listed local handlers: documentation update, configuration review, or test validation.
  6. Generates a synthetic in-memory artifact; it does not execute arbitrary commands or modify an external repository.
  7. Validates the artifact contract, protected boundaries, required evidence, and SHA-256 integrity.
  8. Stores a SQLite receipt containing the policy decision, planner provenance, validation results, artifact hash, status, and next action.
  9. Reopens stored receipts without repeating execution.
  10. Exports repository-scoped Codex work packages in Markdown or JSON.

Protected objectives are blocked before artifact generation. BoundedRun does not access secrets, production systems, financial accounts, personal data, or external infrastructure.

How we built it

We built BoundedRun as a standalone OpenAI Build Week demonstration using only synthetic project data and no private repository content.

The final implementation uses:

  • GPT-5.6 through the OpenAI Responses API
  • strict Pydantic structured-output validation
  • deterministic fallback with explicit provenance
  • Python and FastAPI
  • three allow-listed in-memory handlers
  • SQLite receipt storage
  • SHA-256 evidence tracking
  • Markdown and JSON Codex work-package export
  • an accessible HTML and JavaScript interface
  • GitHub Actions for automated validation

Codex implemented and hardened the primary workflow, expanded the tests, improved accessibility and responsive behavior, added history and export functionality, and documented the final architecture.

The validated build passes 42 tests with 100% application coverage. Ruff, smoke testing, browser QA, JavaScript syntax validation, and GitHub Actions also passed.

Challenges we ran into

The main challenge was not generating code. It was proving that the system remained inside its permitted scope.

We needed to ensure that:

  • policy always runs before planning or execution
  • GPT-5.6 output cannot override a protected boundary
  • malformed or unavailable AI responses fall back safely and visibly
  • only explicitly allow-listed handlers can run
  • protected objectives produce a blocked receipt without an artifact
  • stored evidence can be reopened and exported without repeating execution
  • user-provided or planner-provided text is rendered safely in the browser

Another challenge was making failure behavior understandable. Instead of hiding AI or validation failures, BoundedRun records planner provenance, fallback reasons, validation results, and the next safe action.

Accomplishments that we're proud of

We built an evidence-first execution model rather than an unrestricted autonomous agent.

The final product includes:

  • safe, review, and protected risk classification
  • strict GPT-5.6 structured planning
  • visible deterministic fallback provenance
  • three allow-listed local handlers
  • protected-action blocking before artifact generation
  • stored receipt history
  • receipt reopening without re-execution
  • Markdown and JSON Codex work-package export
  • artifact SHA-256 evidence
  • accessible desktop and mobile interfaces
  • 42 passing tests
  • 100% application coverage
  • successful smoke testing and browser QA
  • passing GitHub Actions validation

The project remains completely isolated from existing private projects, credentials, production infrastructure, and proprietary data.

What we learned

Reliable AI development requires more than strong model output.

The useful unit of automation is a closed execution loop that can:

  • understand an objective
  • classify risk before acting
  • operate only through explicit handlers
  • validate its own result
  • preserve evidence
  • expose planner provenance
  • stop safely
  • communicate the next action clearly

We also learned that deterministic fallback is not merely an error path. It is a core reliability feature that keeps the system testable and auditable even when an AI service is unavailable.

Trust comes from verifiable boundaries, validation, and receipts, not from claiming that a system is autonomous.

What's next for BoundedRun

Future versions could add:

  • reusable policy packs for different repository types
  • integrations with issue trackers and CI platforms
  • cryptographically signed execution receipts
  • organization-level governance dashboards
  • configurable protected-action boundaries
  • additional reviewed and allow-listed handlers
  • multi-project orchestration with strict project isolation
  • historical performance and failure analysis
  • controlled handoff to external Codex workflows without arbitrary command execution

Built With

Share this project:

Updates