Repository Layout

Repository Layout

Repo Steward is one Go module with a single command and a set of internal packages, each owning one concern. The dependency direction is strict: packages lower in this table never import packages above them.

Command

Path	Purpose
cmd/repo-steward	flag parsing, wiring, exit codes, JSON output. No logic that a test would want to call directly.

Packages, from the outside in

Package	Owns	Depends on
steward	the orchestration for inspect, maintain in every mode, resume, outcomes, publication capture, result rendering	almost everything below
bench	scenario execution, scoring, result files, summaries	steward, scenario, fixture, modproxy
inspect	the read-only pipelines: profile, snapshot, cache, discovery, baseline; and the vulns report	repo, snapshot, sandbox, validate, deps, vulnscan
vulnscan	provisioning the pinned scanner and the database, and verified scans in the sandbox	vuln, sandbox, toolchain
vuln	scanner pins, the fail-closed scanner-output parser, database snapshots, the synthetic fixture advisories; runs nothing	none
agent	the model-driven agent: the facts, the fixed system prompt, the opening message, and the labelled tool-result format; the rendering and the reply mapping are the runtime's render	the runtime, tools names
scenario	embedded scripted scenarios with expectations, oracles, and overrides	fixture names
tools	the agent's tool set: seven read-only, four mutating, three terminal	session, manifest, validate, proposal, publish, workspace
policy	the runtime policy: phase gating, eligibility, projected scope, budgets, publication approval	session facts
session	one run's shared state: workspace, profile, target, scope, budgets, phase derived from journals	task, workspace, repo
publish	destination verification, journaled push and pull request, reconciliation	github, gitx, task
github	a minimal REST client and a fake server for tests	none
proposal	readiness evaluation (including the scan rules), the advisory section of the body, freezing a commit from a persisted recipe, recovery, verification	manifest, validate, workspace, task
manifest	staging, Gate A admission, Gate B normalization with the build-list rules, closure, promotion journal and recovery	sandbox, gitx, task
validate	build, vet, and test in the execute profile with fail-closed parsing and stable finding keys	sandbox
deps	candidate discovery and per-version eligibility, including the version cooldown; PlanVulnFixes for vulnerable selection	sandbox
workspace	scratch clone with a separate git directory, contained reads, candidate tree, diff	gitx, snapshot
task	the SQLite tables this project adds beside the runtime's: tasks, promotions, validations, vulnerability scans, proposals, publication operations	none
repo	repository profile, refusals, protected-path matching	snapshot entries
snapshot	candidate tree from a seeded index, exact materialization with verification, limits	gitx
sandbox	container profiles (acquire, mutate, execute, tool), fresh build caches, mount probe, orphan reaping, output caps	dockerapi, toolchain
sandbox/dockerapi	a minimal Docker Engine API client over a unix socket	none
toolchain	the digest-pinned image table keyed by Go directive	none
modproxy	a file-based module proxy generated from embedded module sources	none
fixture	embedded fixture repositories and modules with pinned ids	gitx
gitx	the Git command-line wrapper with fixed argv and isolated configuration	none
lock	exclusive OS file locks	none
faultpoint	fault injection points, compiled in only under the faultinject build tag	none
testtmp	temporary directories the container engine can see, for integration tests	none
smoke	pinned scenarios against real public modules, under the smoke build tag: the baseline pipeline, vulnerable selection, and the on-demand repair scenarios	steward, deps, gitx

What the runtime supplies instead

These were written here and were deleted once the runtime shipped them, so there is one copy to fix and one set of tests to trust.

Was	Now
model/ollama, model/anthropic	agent-runtime/providers/ollama and agent-runtime/providers/anthropic, nested modules with their own go.mod, plus the shared providers helpers for transport classification, price lookup, and dollar parsing
the price table and the "a paid model runs only with a known price" refusal	anthropic.Prices() with providers.PriceFor; a local model is priced free with ollama.Free
the renderer and the reply-to-decision mapping in agent	agent-runtime/render, configured with this repository's hooks
the stderr trace observer in cmd/repo-steward	agent-runtime/trace.Writer, the identical format
the flattening of runtime rows in runs list and runs show, and the "one pending approval" selection in approve and reject	agent-runtime/view: Summary, Steps, PendingApproval. The joins with this repository's task, proposal, and promotion tables stay here
the two hand-built require_approval decisions in policy	agentrt.NeedApproval

Other directories

Path	Contents
docs/	architecture, security, status, and decision records, versioned with the code
benchmarks/	scoring rules and every result file produced by bench run
internal/fixture/testdata/fixtures/repos/<name>	fixture repositories; go.mod is stored as go.mod.embed because go:embed refuses nested modules
internal/fixture/testdata/fixtures/modules/<path>@<version>	fixture dependency modules served by the proxy
internal/scenario/testdata/scenarios/*.json	scenario declarations
internal/smoke/testdata/repair, internal/smoke/testdata/vulnerable	declarations of the repair scenarios on real repositories, and of the real-advisory scenario
internal/steward/testdata/recordings/<model>/<fixture>	recorded model responses replayed in CI
.github/workflows/smoke.yml	the smoke scenarios against public modules, on demand and weekly
.github/workflows/ci.yml	unit, integration, fault-injection, replay, publication, and approval smoke jobs

The scan code is described in Vulnerability Scan Pipeline.

Where to start reading

For the control flow, read steward/baseline.go first: it is the whole pipeline with no agent. Then steward/agent.go, which runs the same stages through the runtime with tools and policy. Then tools/ and policy/ together, because every tool's argument shape is what the policy evaluates.