ci: scope every expensive job to a capability vector — paths decide, labels override

[rickylabs]

Summary

Every expensive CI job except the two scaffold tiers runs unconditionally on every pull request.
check-test (~7 min) and quality (~2 min) have no job condition at all, so an RFC or a
one-file documentation change pays the same toolchain bill as a change to packages/service.

The fix is not more workflow YAML. .github/scripts/ci-classify-changes.ts already exists, is
pure, unit-tested, and conservative by design — "an unrecognised path forces the gate to run. It
NEVER skips because it failed to classify." It just answers only two questions, for one workflow.
Promote it to a capability vector that every expensive job reads.

Measured — last 20 closed PRs

Job	Gate today	Total	Ran on
check-test	none — always runs	~138 min	20/20
scaffold-runtime (aspire + docker + postgres)	classifier	~128 min	15/20
scaffold-static (deno-only)	classifier	~46 min	15/20
desktop-native-linux	declared, not honored (tracked separately)	~41 min	20/20
quality	none — always runs	~38 min	20/20

≈390 min / 20 PRs ≈ 19.5 min per PR.

Five of the twenty touched no shipping code: #1123 (RFC), #1086, #1063, #1053, and #1055 —
which changed one file under .agents/. The classifier correctly skipped both scaffold tiers on
all five. Each still burned ~10 minutes on check-test + quality + desktop-native-linux,
because those jobs never consult it.

That is the RFC gap precisely located: the docs-only skip does fire for RFCs — just not on the
jobs that cost the most.

Design — one classifier, many consumers

Emit a capability vector once per PR, consumed by ci.yml and e2e-cli.yml alike:

Output	Consumers	Path signal (starting set)
needs_deno	check-test, quality	packages/**, plugins/**, apps/**, deno.json*, deno.lock
needs_docker	docker tier of scaffold-runtime	database/queue/cache packages, Aspire helper generation, Prisma schema, plugins/**
needs_desktop	desktop-native-linux	deploy / desktop / packaging paths
needs_docs	docs accuracy, link integrity	docs/**
needs_surface	surface-diff	already path-filtered; fold in for one decision point

Invert the docker default

scaffold-static (deno-only) and scaffold-runtime (aspire + docker + postgres) already form two
tiers. What is missing is that any packages/** change escalates to the docker tier. Docker
should be the exception, reached on needs_docker, with a deno-only runtime tier as the default —
this is the single largest line in the table.

Paths are the mechanism; labels are the override — ratified 2026-08-03

Keep exactly the three labels that exist: ci:full, ci:skip-scaffold, ci:skip-e2e.

Add no per-technology labels (postgres, prisma, redis, docker, …). Deriving routing from
labels moves the decision into GitHub's label UI, where it cannot be unit-tested and every author
must remember to apply it — and the label set grows without bound until it is itself unmaintainable.
The classifier is tested code; labels are untested configuration. Prefer the tested one. A human who
knows better reaches for ci:full; nobody has to remember to tag postgres.

Two risks to hold

1. A skipped job must still report, or it stops being required. scaffold-static already
   solves this — it starts and reports success with a skipped-by-policy step. Reuse that pattern for
   check-test and quality; do not invent a second one, and do not simply drop the jobs.
2. needs_docker's path set is the dangerous one. Too narrow and a wiring regression ships.
   Start it deliberately wide and tighten only against observed green history — the same
   "additive until observed green" discipline e2e-cli.yml already documents for the runtime lane.

Acceptance

• ci-classify-changes.ts emits the capability vector above, unit-tested per output
• check-test and quality consult needs_deno and report skipped-by-policy when it is false
• scaffold-runtime splits into a deno-only default tier and a docker tier gated on
  needs_docker
• No second routing table exists in workflow YAML — jobs read classifier outputs only
• The label set is unchanged: ci:full, ci:skip-scaffold, ci:skip-e2e, and no others
• Conservative default preserved: an unrecognised path still forces the gate to run
• Measured before/after on a comparable PR sample, recorded on this issue

Provenance

Owner observation 2026-08-03: the Actions queue grows with parallelised agent PRs and most PRs run
CI unrelated to their scope. Measured over the last 20 closed PRs. The
desktop-native-linux wiring defect found in the same audit is tracked separately as a discrete
fix that can land ahead of this redesign.

[rickylabs]

Discrete wiring fix split out as #1151 so it can land ahead of this redesign — it is a one-condition change worth ~41 min per 20 PRs on its own.

[rickylabs]

Worked example — PR #1122 ran the full aspire+docker+postgres suite because it edited release-canary.yml

Contributing this as evidence, per the owner. It shows the IMPACTING set is too coarse in a specific and fixable way rather than merely expensive.

What happened

PR #1122 (canary label surface) changed exactly these categories:

Category	Example
.github/workflows/	release-canary.yml
deno.json	added a release:canary-label task
.llm/tools/release/**	canary-label.ts, preflight-text-imports.ts, prepare-release.ts, canary.ts
.llm/tools/	generate-publish-assets.ts
.llm/runs/**	run artifacts

Zero packages/**. Zero plugins/**. Verified: gh pr diff 1122 --name-only | grep -cE '^(packages|plugins)/' → 0.

ci-classify-changes.ts treats .github/workflows/ as IMPACTING_PREFIXES and deno.json as IMPACTING_EXACT. Both blanket-force the gate, so the PR ran scaffold-runtime (aspire + docker + postgres).

It then failed, and the failure was pure waste

> runtime.aspire-restore: Restore Aspire TypeScript SDK
  FAILED 900122ms

900122ms is the 15-minute ceiling — a timeout during an SDK restore, in a suite that cannot be affected by editing the release-canary workflow. Two full runs of that suite were spent (one original, one re-run) before the cause was understood. That is ~30 minutes of aspire+docker+postgres time on a release-tooling PR.

The precise, narrow fix this supports

.github/workflows/** should not escalate wholesale. Only the workflows that define the scaffold tiers — e2e-cli.yml and ci.yml — plus genuine toolchain changes in deno.json, should force them. release-canary.yml, pages.yml and their peers cannot affect scaffold behaviour by construction.

Note deno.json deserves the same discrimination: adding a task is not a toolchain change. This PR added release:canary-label and that alone forced the gate. A change to imports/workspace/engine constraints is materially different from appending a script alias.

Why paths-as-mechanism is right here

The owner's ratified design — paths are the mechanism, labels are override only, no per-technology labels — is exactly what this case needs. Nothing about a per-technology label would have helped: the correct signal was already present in the path list and was simply read too coarsely. The override (ci:skip-e2e + ci:skip-scaffold, now applied to #1122) is the right escape hatch and the wrong permanent answer.

Cost data point

Add 2 × scaffold-runtime to the audit for a PR whose diff could not affect it — on top of the check-test and quality runs #1152 already counts.

Cross-ref: #1151 (desktop-native-linux ignoring env.RUN) fired on this PR too, for the same underlying reason.

Not implementing — #1151/#1152 are delegated. Filing this as evidence only.