feat(pipeline): let a stage be granted permissions beyond the baseline

[pedromvgomes]

Why

Every orchestrator stage job gets a fixed baseline — contents: read + packages: read for CI, contents: write + packages: write for CD — and a called workflow can only ever narrow what its caller grants. A leaf needing a scope the baseline withholds cannot ask for it back. The template said so outright:

A stage needing more than this is a gt change.

This is that change, and wardnet is the repository it unblocks. Two of its eight pr.yml leaves need more:

leaf	needs	why
build-daemon	security-events: write	codeql-action/upload-sarif for clippy SARIF
tests-e2e	packages: write	--cache-to type=registry,...buildcache

Neither would fail loudly on migration. The SARIF upload and the cache export would just stop happening while the pipeline stayed green — which is precisely the "green forever" defect this rollout exists to remove. Without this the only honest option was pipeline.ci.enabled: false, leaving wardnet off the CI pipeline indefinitely.

What

pipeline:
  ci:
    stages: [preflight, build, test, end2end]
    stage_permissions:
      build:
        security-events: write   # codeql-action/upload-sarif
      end2end:
        packages: write          # --cache-to type=registry

• Merged over the baseline: a named scope is raised (packages: read → write), everything unnamed is untouched.
• Per-stage. Only the named stage is widened; a grant never reaches its siblings.
• Available for CD too (pipeline.cd.stage_permissions), since that template carried the same "is a gt change today" note.
• Rendered comments explain a widened stage differently from a baseline one, so the diff says why a job holds a write scope.

Validation

Stage names and the scope/level vocabulary are both checked at sync time. The scope list is enumerated rather than passed through deliberately: GitHub ignores an unknown scope silently, so code-scanning: write would render a job that reads as widened, passes review, and fails later at the one API call it was meant to permit.

Rejected: a stage that isn't enabled, an unknown scope, an invalid level, an empty scope map, and any grant while the pipeline is disabled.

Backwards compatibility

This is the part worth checking rather than trusting, so I checked it. I rendered every file on origin/main gt and on this branch and diffed:

• With comments stripped, both orchestrators are byte-identical. No directive moves, no repo's behaviour changes.
• The field is omitempty, so no existing .gt-repo.yaml gains a key and the "only overrides are written" rule holds.
• The comments do change, so the next fleet sync is a comment-only diff in ci-orchestration.yml (and cd- where enabled). Expected, and worth knowing before it shows up across 17 repos.

Scopes render sorted, so Go's randomised map iteration can't make a re-render look like drift — there's a test asserting 20 consecutive renders are identical.

Tests

• baseline pinned for every CI and CD stage, so a future change can't silently rewrite the fleet
• widening adds a withheld scope, raises an existing one, and leaves sibling stages untouched
• CD widening
• deterministic rendering
• five new validation cases

go test ./..., go vet ./..., gofmt all clean.

[github-actions]

bulwark

• ✅ scan — no findings

• ✅ coverage — see error output below

📦 Full bulwark output — complete scan and coverage logs.