[Sprint] sprint-loop-38

[scealiontach]

Sprint plan: 2026-05-06 sprint-loop-38

Sprint goal

This sprint prioritizes production safety and release-tooling correctness, then locks in documentation for two core developer surfaces (options::parse and @include), and adds focused bats coverage for log::level_decrease and PagerDuty JSON helpers. Together these items reduce silent failures under set -e, prevent misleading semver tag bumps on lightweight tags, and make hidden library contracts discoverable without reading AGENTS.md alone.

Selected issues

SUR-2490 — Bug: log::level_decrease has stray calling this line that breaks decrement in set -e contexts

• Description summary: A bare calling this line inside log::level_decrease in bash/log.sh runs as a command (127) and aborts callers under set -e before the decrement runs; bats missed it because the test subprocess does not use set -e. Remove the stray line and fold the prose into a continued @doc block as specified in the issue.
• Rationale: This is a correctness and availability bug for any production script sourcing log.sh with set -e; it should land before expanding tests in SUR-2476 so behavior and expectations stay aligned.
• Definition of Done:
  • Stray calling this removed; @doc has no bare words executed as commands.
  • Explicit test (or subshell) proving decrement from non-zero LOG_LEVEL under set -e completes without error.
  • pre-commit run --all-files passes.
  • Issue acceptance checklist from Linear satisfied.
• Dependencies / ordering: First among log-related work; SUR-2476 should follow so tests reflect the fixed implementation.

SUR-2457 — Bug: update-repo-tags prerel increment silently misbehaves when existing prerel is non-numeric

• Description summary: The lightweight-tag path in bash/update-repo-tags uses ((PREREL++)) on a string prerel, coercing non-numeric values to 0 and corrupting the next tag; substitution can also match the wrong -$PREREL segment. Add an explicit guard (issue suggests warning + reset or equivalent product decision) and tests for non-integer / non-numeric prerel on that path.
• Rationale: Silent wrong tags are high-impact for release hygiene; fixing this protects automated tagging flows.
• Definition of Done:
  • Non-numeric or empty prerel no longer produces silently wrong next tags without an explicit, logged or failing behavior agreed in code review.
  • Tests cover the lightweight-tag prerel path for at least non-numeric and edge cases called out in the issue.
  • bash/update-repo-tags and any touched libs stay shellcheck-clean.
  • make test (or targeted bats + sprint tests) passes.
• Dependencies / ordering: Independent of log work; can parallelize with docs once branch is cut.

SUR-2476 — Test: log::level_decrease has zero test coverage and no callers in the codebase

• Description summary: log::level_decrease lacks bats coverage and in-repo callers; older text in the ticket shows a minimal ((LOG_LEVEL--)) body—reconcile with current bash/log.sh after SUR-2490. Add tests for decrement from a positive baseline and for behavior at LOG_LEVEL=0 (guard vs error per current implementation), and clarify public API intent in @doc or justify retention.
• Rationale: Prevents regressions after the SUR-2490 fix and documents the contract for external consumers.
• Definition of Done:
  • tests/log.bats exercises decrement and the zero-level path consistent with the implementation.
  • @doc (or adjacent comment) states intended use if the function remains public.
  • Any new guard matches project style and is covered by tests.
  • CI/pre-commit green.
• Dependencies / ordering: After SUR-2490 merge or same branch sequence so tests target final function body.

SUR-2473 — Docs: options::parse NO_SYNTAX_EXIT escape hatch is undocumented in @doc annotations

• Description summary: options::parse consults NO_SYNTAX_EXIT to skip the no-args syntax exit; this is undocumented in @doc / @arg, so bashadoc and readers miss it. Extend annotations to describe when to set it and the leak risk; optionally document options::parse_available as non-exiting.
• Rationale: Reduces hidden global state and copy-paste misuse across commands that legitimately allow zero-flag invocations.
• Definition of Done:
  • @doc / @arg on options::parse mentions NO_SYNTAX_EXIT semantics.
  • options::parse_available documented as not performing the syntax exit (per issue suggestion).
  • Generated docs (if applicable) and shellcheck remain clean.
• Dependencies / ordering: Independent; low risk early merge.

SUR-2474 — Docs: includer.sh @include function lacks @doc annotation and deduplication behavior is unexplained

• Description summary: @include has no @doc (and bashadoc skips @ names); add a block comment describing resolution order, cksum deduplication, symlink/hardlink consequences, and return-1 vs exit behavior; mirror resolution notes on includer::find as requested.
• Rationale: @include is load-bearing for every library; undocumented dedup semantics have surprised advanced use cases.
• Definition of Done:
  • Comment block above @include matches behavior in bash/includer.sh.
  • Parallel documentation on includer::find for resolution order.
  • No behavioral change unless a clear bug is found during review.
• Dependencies / ordering: Independent.

SUR-2479 — Test: pagerduty::_incident_data empty incident_key conditional omission is untested

• Description summary: Add tests/pagerduty.bats covering JSON with and without incident_key when empty vs non-empty, plus pagerduty::send_incident behavior with --fail-with-body on HTTP error using a mocked curl, respecting commands::use / jq availability.
• Rationale: Closes a real branch gap in incident payload construction and hardens HTTP failure handling.
• Definition of Done:
  • New bats file with the three behaviors described in Linear acceptance criteria.
  • Mocks isolate network; tests run in standard make test / pre-commit bats hook.
  • Document any new test helpers following tests/helpers.bash patterns.
• Dependencies / ordering: Independent; moderate effort—schedule after quick wins if capacity tight.

Risks + mitigations

• Stale issue text vs repo: SUR-2476’s embedded snippet may predate SUR-2490’s body—mitigate by re-reading bash/log.sh on branch and updating tests to match reality.
• Semantics choice on SUR-2457: Warning+reset vs hard-fail affects operators—mitigate by matching the issue’s suggested guard or documenting deviation in PR.
• PagerDuty mocking complexity: Curl/jq interactions can be fiddly in bats—mitigate by studying existing mock patterns in other tests/*.bats files.
• Doc-only changes still affect pack-script/bashadoc surfaces: Mitigate with make test and any doc generation targets touched by CI.
• Concurrent edits to log.sh: Mitigate by keeping SUR-2490 and SUR-2476 on the same sprint branch or strictly ordered PRs.

Out of scope

• Linear issues left in Backlog for this sprint: SUR-2470, SUR-2477, SUR-2478 (not selected).
• Issues outside project shell-scripts or team Surinis, or any status other than Backlog at selection time.
• Work driven solely by the team-scoped manual label (none encountered in this review).
• Dependency Filter B had no open PR file list entries ([]), so no PR-overlap exclusions were applied.

Linear Evidence

• Linear team verified: Surinis (list_teams query "Surinis"; team id ce9ebfde-ff2b-4f54-90f1-c388591ca110).
• Linear project used: shell-scripts (project id a43901a0-b02b-4009-aae1-a6e8903d127d; list_projects confirms it is attached to team Surinis).
• Query / filter used: list_issues with project=shell-scripts, team=Surinis, state=Backlog, limit=250, includeArchived=false, orderBy=updatedAt; per-issue get_issue(..., includeRelations=true) for blockedBy; per-issue list_issues with parentId=<candidate> to detect sub-issues; list_comments for each selected issue.
• Approx count of Backlog issues reviewed: 9.
• 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 []

Sub-issue Status

No reviewed Backlog candidate had Linear sub-issues: list_issues with parentId set to each of the nine Backlog issue identifiers returned empty lists. No parent rows were skipped for incomplete children.

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

Linear State Transitions

Issue ID	Previous State	New State
SUR-2490	Backlog	Todo
SUR-2457	Backlog	Todo
SUR-2476	Backlog	Todo
SUR-2473	Backlog	Todo
SUR-2474	Backlog	Todo
SUR-2479	Backlog	Todo