Auto-scope: skipping runs that cannot fail

Most CI time is spent proving that a change you already know is inert did not break anything. A README fix runs the same suite as a rewrite of the scheduler.

Auto-scope is Agentic Pipeline deciding that for you. On each push to a non-default branch it compares your branch's whole diff against the merge base with your default branch, and asks one question: could any of these files possibly affect any stage of this repo's recipe? If — and only if — the answer is provably no, the run is concluded green with every stage recorded as skipped, and no executor is booted at all.

It is deliberately run-level and all-or-nothing. There are no partial auto-skips: skipping some stages while running others creates skipped-ancestor/running-dependent hazards you never reasoned about when you wrote the recipe. Partial scoping stays yours, via if_changed.

Legend: the red path is the default and the fallback for every uncertainty — auto-scope broadens rather than skips whenever it cannot prove the case.

What an auto-scoped check looks like

The required RunsGreen check goes green with the title:

native: success (auto-scoped, 0s — docs-only diff)

The summary names every skipped stage, the class of the diff, the merge-base commit it diffed against, and the exact config key that turns the behaviour off. Read it — it is the whole record. An auto-scoped run has no log, because nothing ran: slipstream_log_get and slipstream_diagnose have nothing to return for it. The dashboard shows the same thing as an Auto-scope: skipped badge on the run's detail row.

What counts as inert

The class is narrow on purpose, root-anchored, and case-sensitive (git paths are):

Inert	Not inert
Anything under the top-level docs/	A nested docs/ — docs-site/docs/** is product source
*.md at the repo root (README.md, AGENTS.md, …)	packages/foo/README.md — markdown is a build input in content trees
Root LICENSE / NOTICE (bare, .md, .txt)	.gitignore (ESLint, turbo and git clean all honour it)
	CODEOWNERS (repos validate it in CI)
	README.MD, Docs/ — the wrong case is simply not a match

Even when every path is inert, the run still executes in full if any of these hold:

• A stage mentions a changed file. Any stage cmd, stage env value or key, or recipe-level env containing the path, its basename, or its first path segment (case-insensitive). If your docs-site build stage's command contains docs, your docs pushes always run.
• An explicit if_changed matches. You already declared this diff relevant, and your declaration wins. The matcher follows git pathspec semantics — the same rules the executor's own git diff -- <pathspec> uses, where * and ? cross /.
• The recipe uses turbo affected scoping, or carries the broad **/* sentinel. Auto-scope does not model turbo graphs.
• Anything is unresolvable: no repo-owned .slipstream.json at that sha, a compare API error, a diff of 300+ files, a behind/identical compare, an empty file list, or a pathspec construct the matcher cannot fully model (:(exclude), !, [...] classes).

Two things are never auto-scoped, by design:

• Your default branch. The post-merge run stays the exhaustive safety net, and it is what gates deploys — so a mistaken skip on a PR is caught loudly there.
• Reruns. Asking for a rerun means "execute this for real".

Modes, and turning it off

Auto-scope is per repo and instantly reversible.

Mode	What happens
off	Nothing. The default for every repo.
annotate	The decision is recorded on the run and a would-skip run gets one advisory line on its check. Nothing that executes changes.
enforce	A proven-inert diff is concluded green without booting an executor.

enforce is reached automatically: once a repo's annotate verdicts have proven accurate over the evidence window, Agentic Pipeline writes slipstream.auto_scope.<owner>/<repo>=enforce itself (fleet key slipstream.auto_scope_graduate, on by default) and announces it. Setting the per-repo key yourself — to annotate, enforce, or off — freezes it there; the platform never overrides a row that already exists. To turn it off, or to step back to evidence-only, ask an operator for:

PUT /api/slipstream/config
{ "slipstream.auto_scope.<owner>/<repo>": "off" }

It takes effect on your next push; nothing needs redeploying. Setting annotate instead keeps the evidence flowing while running everything.

Living with it

• Auto-merge still works. An auto-scoped green fires the same auto-merge path a real green does, so a docs PR in an opted-in repo merges normally.
• slipstream_prewarm is wasted work under enforce. The usual agent flow is prewarm → push → follow; on a docs-only push under enforce the prewarm wakes a machine that is then never used. Harmless, but skip it if you know the push is docs-only.
• Statistics exclude auto-scoped runs. A 0-second success is not evidence about how fast your pipeline is, so fleet and repo duration rollups drop these rows and report the count separately.
• If a would-skip run ever fails for real, the platform pages itself and that repo does not get enforce until the class is tightened. Auto-scope is gated on measured accuracy, not on optimism.