Home

Repo Steward

Repo Steward is a command-line tool that performs one bounded dependency upgrade on a local Go module, validates it inside a sandbox, repairs what the upgrade broke within explicit limits, and prepares a pull request that a human approves before anything leaves the machine. It is the first application built on agent-runtime, a small Go runtime for tool-using agents under deterministic control.

The problem it addresses: dependency bots open version bumps and stop when the build breaks. The expensive part, reading the error, finding the changed API, fixing the call sites, and re-validating, is left to a person. Repo Steward does that part, under controls the model cannot influence, and hands back a reviewable pull request.

Repo Steward can also report the known vulnerabilities that affect a repository (vulns) and, in its no-model mode only, fix one by choosing the smallest upgrade that clears it. See Vulnerabilities: Reporting and Fixing. On real repositories the local model has not yet repaired any break it was given (0 of 9 runs); see Evidence and Benchmark Results.

Start where you are

If you are...	Read
Someone who wants to run it	Getting Started, Command Reference, Modes, Vulnerabilities: Reporting and Fixing, Publication, Troubleshooting and FAQ
A developer who wants to understand or change it	Repository Layout, Architecture, Sandbox, Manifest Gates and Promotion Journal, Validation and Readiness, Vulnerability Scan Pipeline, Tools and Policy, Agent and Models, Testing, Contributing
Responsible for operating it, or deciding whether to	Executive Summary, Security Model, Threat Model, Data and Privacy, Cost and Spend Controls, Reliability and Recovery, Evidence and Benchmark Results, Roadmap and Status
Curious why it is built this way	Design Decisions, Glossary

The one-paragraph version

A run clones your checkout into a scratch workspace, profiles it, validates the unchanged code in a container with no network, and lists outdated direct dependencies with a per-version verdict from your policy. An upgrade is applied by the Go toolchain against a staging copy of the manifests and admitted only if explicit rules pass. The agent, either a deterministic pipeline, a scripted decision list, or a local model, repairs source within scope limits using scoped tools; every request is validated and policed by the runtime before it runs. Validation is bound to the exact tree it ran on, and so is a vulnerability scan. A proposal is frozen as a commit with a persisted recipe. Publication requires a separate approval bound by hash to that proposal, and the push and pull request are journaled so an interruption is reconciled against the remote rather than replayed.

Where the source of truth lives

The repository's docs/ folder holds the architecture, security, status, and decision documents that ship with the code and are versioned with it. This wiki explains the same system at more length and from more angles. Where they differ, the repository documents win, because they change with the code.