[Sprint] sprint-loop-35

[scealiontach]

Sprint plan — 2026-05-05 sprint loop 35

Sprint goal

Deliver a tight slice of correctness, safety, and operator trust across the shell-scripts codebase: fix silent failure modes in git branching and Docker registry calls, bound AWS ECR scan polling so CI cannot spin forever, align release-images with shared logging conventions, enforce the documented mandatory-options contract in options.sh, and harden PagerDuty incident submission against xtrace leaking bearer tokens. Together these issues reduce wrong-success outcomes, improve diagnostics, and close gaps between documented CLI behavior and runtime enforcement.

Selected issues

SUR-2322 — Bug: options::add -m (mandatory) flag is decorative — never enforced

• Description summary: -m only affects help text (options::doc / options::syntax); options::parse never rejects missing required flags, so globals stay empty and scripts proceed with dangerous defaults (empty label selectors, cryptic ${1:?} failures downstream). Fix should post-parse walk OPTIONS / OPTIONS_OPTIONAL, track whether options were seen (including parse-fn-only options), and call options::syntax_exit when required options are absent or empty-string.
• Rationale: Restores the framework contract many commands already assume; improves failure messages and prevents silent wide-scope operations.
• Definition of Done
  • Post-parse validation enforces mandatory options per issue description (non-empty env or parse-fn invoked as specified).
  • Empty string passed for a mandatory option is rejected (-l "" case).
  • tests/options.bats covers missing mandatory flag and empty-arg cases.
  • Existing command scripts using -m still pass make test / relevant bats specs (adjust tests or call sites only if required).
• Dependencies / ordering: Prefer completing early in the sprint so any follow-on test fixes land while context is fresh; coordinate with SUR-2344 if release-images bats need explicit flags after enforcement tightens.

SUR-2334 — Anti-pattern: switch-to-branch -n silently falls back to plain checkout when -b fails

• Description summary: When NEW_BRANCH=true, failed checkout -b falls through to plain checkout, hiding errors via exec::hide. Exclusive -n path should only attempt create, log failure with visible git output (exec::capture), and not switch onto an existing branch.
• Rationale: Prevents cross-repo silent wrong-branch states and surfaces “branch already exists” class failures.
• Definition of Done
  • -n path does not fall through to existing-branch checkout on -b failure.
  • Git errors are visible in logs (per issue: use exec::capture pattern).
  • tests/switch-to-branch.bats covers existing branch scenario: warns/errors appropriately and does not move HEAD to existing branch when -n was requested.
• Dependencies / ordering: Independent of other sprint items; can run parallel after small shared infra (none).

SUR-2337 — Bug: docker::registrycmd builds malformed Authorization: Basic null when registry missing from ~/.docker/config.json

• Description summary: jq -r emits literal null; curl sends Authorization: Basic null. Validate token (jq default + explicit checks), log::error with actionable message, return non-zero; prefer curl -fsS for HTTP failures.
• Rationale: Stops silent empty/wrong repository lists that can mislead release promotion flows.
• Definition of Done
  • Missing or null auth entry short-circuits with non-zero exit and clear log line (docker login hint).
  • curl failures propagate appropriately (-fsS or equivalent agreed behavior).
  • tests/docker.bats uses isolated HOME with empty ~/.docker/config.json and asserts failure for registry without auth.
• Dependencies / ordering: Independent; before heavy release-images manual testing if desired, not blocking.

SUR-2339 — Anti-pattern: pagerduty::send_incident does not silence xtrace around Authorization Token header

• Description summary: With set -x, curl command line leaks PagerDuty token. Apply { set +x; } 2>/dev/null pattern consistent with secret.sh; optionally consider _incident_data for consistency per issue.
• Rationale: Prevents secret materialization in CI logs under debug tracing.
• Definition of Done
  • pagerduty::send_incident disables xtrace (or equivalent safe pattern) before token-bearing curl.
  • tests/pagerduty.bats enables set -x, records/mocks curl, asserts trace output does not contain token string.
• Dependencies / ordering: Independent.

SUR-2340 — Bug: aws::wait_for_scan_complete loops forever with no timeout / max attempts

• Description summary: Unbounded while ! aws::is_scan_complete can hang on FAILED, stuck IN_PROGRESS, or bad status. Add max attempts + sleep, fast-fail FAILED, trace logging for intermediate states, timeout error.
• Rationale: Protects CI minutes and gives operators polling visibility.
• Definition of Done
  • Bounded wait with configurable max attempts / timeout semantics matching agreed defaults from issue (~30 × 10s default or documented alternative).
  • FAILED returns non-zero promptly with log::error.
  • Non-terminal states log at trace (or agreed level) with attempt counts.
  • tests/aws.bats mocks non-COMPLETE status path and asserts bounded exit (non-infinite).
• Dependencies / ordering: Independent.

SUR-2344 — Anti-pattern: release-images forces log::level 2 and defines no-op usage()

• Description summary: Remove forced log::level 2 before parse (let options::standard / -v drive verbosity); delete dead usage function; align with other bash/ commands.
• Rationale: Removes surprise INFO noise and dead global usage symbol.
• Definition of Done
  • Forced pre-parse log level line removed; behavior matches repo norms (or documented deviation if product insists, per issue preference for -vv).
  • Dead usage removed.
  • make test_bats / tests/release-images.bats still passes; update expectations if log volume assertions existed.
• Dependencies / ordering: After SUR-2322 if mandatory-option enforcement changes CLI tests for release-images; otherwise parallel.

Risks and mitigations

• Mandatory-option enforcement surfaces latent bugs — Many scripts rely on undocumented “empty means all” behavior; mitigations: staged rollout on sprint branch, run full make test, add targeted bats for high-risk commands listed in SUR-2322.
• AWS / Docker tests may need careful mocking — Real network calls unacceptable; mitigations: follow existing bats patterns (helpers::isolate_home, sourced libs, mocked functions).
• switch-to-branch integration complexity — Multi-repo behavior hard to fully simulate; mitigations: focused bats with temp git dirs mirroring existing spec style.
• PagerDuty test flakiness with set -x — Trace format varies by bash version; mitigations: assert on absence of token substring only, tight mock of curl.
• Sprint scope creep — Six items touch distinct subsystems; mitigations: land smallest diffs first (SUR-2344, SUR-2337), keep SUR-2322 scoped strictly to parse validation without refactors.

Out of scope

• Issues outside Linear project shell-scripts or team Surinis.
• Triage / In Progress / Blocked / Done items not in this Backlog pull.
• relatedTo dependency grooming (not used as blockers per planning rules).
• Non-manual-label workflow beyond skipping that label (none encountered this run).
• Open PR file-overlap analysis (precomputed list was empty).
• Product or documentation changes not implied by the selected Linear descriptions.

Linear Evidence

• Linear team verified: Surinis (ce9ebfde-ff2b-4f54-90f1-c388591ca110, key SUR)
• Linear project used: shell-scripts (a43901a0-b02b-4009-aae1-a6e8903d127d)
• Query / filter used: list_issues with project=shell-scripts, team=Surinis, state=Backlog, limit=250, includeArchived=false; per-issue get_issue(..., includeRelations=true) for blockedBy; list_issues(parentId=<each candidate>) for sub-issues; list_comments(issueId=<each candidate>) for full comment threads.
• Approx count of Backlog issues reviewed: 6
• Approx count of manual-labelled Backlog issues skipped: 0
• Issues skipped due to unmerged blockers: 0 []
• Issues skipped due to open-PR file overlap: 0 [] (OPEN_PR_FILES was [])

Sub-issue status

No candidate in the reviewed Backlog set had Linear sub-issues (list_issues with parentId set to each candidate returned empty). No parent was skipped for incomplete children.

Parent Issue	Sub-issue	Sub-issue Status	Eligible?
—	—	—	N/A (no parent/child rows)

Linear state transitions

Issue ID	Previous State	New State
SUR-2322	Backlog	Todo
SUR-2334	Backlog	Todo
SUR-2337	Backlog	Todo
SUR-2339	Backlog	Todo
SUR-2340	Backlog	Todo
SUR-2344	Backlog	Todo