[Sprint] sprint-loop-40

[scealiontach]

Sprint Plan — 2026-05-06 (sprint-loop-40)

⚠️ Insufficient Backlog Warning: Only 1 eligible Backlog issue was found in the shell-scripts project after applying all filters (manual-label exclusion, sub-issue dependency rules, blocker dependency check, and open-PR file-overlap filter). The ideal sprint size is 3–7 issues. This sprint proceeds with the single available issue rather than failing the run.

---

Sprint Goal

Resolve the specification–implementation gap left open after PR #35 (SUR-2477): either extend aws::refresh_scan to honour image-push time as an additional cache-invalidation signal (product change path), or align the Linear acceptance criteria and test commentary to match the implemented cache-window semantics (spec-alignment path). Either path closes the outstanding DoD gap cleanly within the repo.

---

Selected Issues

SUR-2503 — SUR-2477 follow-up: push-vs-scan acceptance vs aws::refresh_scan cache-window behavior

Linear URL: https://linear.app/surinis/issue/SUR-2503/sur-2477-follow-up-push-vs-scan-acceptance-vs-awsrefresh-scan-cache

Description summary:

PR #35 (SUR-2477) shipped four bats tests that cover aws::refresh_scan using mocks for aws::_describe_findings, aws::scan_image, and date. The tests validate:

• COMPLETE scan within the days_ago rolling cache window → skip re-scan
• COMPLETE scan older than the cache window → re-scan
• Non-COMPLETE scan status → re-scan
• Fractional imageScanCompletedAt floored by jq → no spurious re-scan

However the original SUR-2477 Linear issue and its DoD described push-time semantics ("if push is newer than scan → re-scan", "if scan is newer than push → skip"). The live bash/aws.sh implementation reads only imageScanCompletedAt; it never reads imagePushedAt. This leaves a documented-but-unresolved gap between spec language and code.

Two resolution paths are available (the implementor must choose one):

1. Product change — extend aws::refresh_scan to also fetch imagePushedAt from ECR (via aws::_describe_findings or a new helper), add logic for push-newer-than-scan → force re-scan, and add bats coverage for the new code paths.
2. Spec alignment — update the SUR-2477 description / DoD wording (and any sprint commentary) to reflect the actual cache-window semantics, and optionally refactor the existing four bats tests to mock aws::scan_status / aws::cmd at the level described in the original checklist, for added clarity.

The issue is classified as fully in-repo (bash + bats and/or Linear text edits), requiring no credentials or external vendor access.

Rationale:

This is the only available Backlog issue. It represents legitimate unresolved scope from the previous sprint (SUR-2477) and is fully self-contained. Addressing it removes the spec ambiguity before it confuses future contributors or automated agents.

Definition of Done:

• A path is chosen (product change or spec alignment) and documented as a comment on SUR-2503 before or during implementation.
• If product change: aws::refresh_scan reads imagePushedAt and re-scans when push timestamp is newer than the last scan completion timestamp.
• If product change: bats tests cover push-newer-than-scan → re-scan and scan-newer-than-push (within cache window) → skip paths, using appropriate mocks.
• If spec alignment: SUR-2477 description and/or DoD wording is updated to accurately describe the cache-window (days_ago) semantics actually implemented.
• If spec alignment: existing four bats tests are optionally refactored for clarity (mock level adjusted), but do not regress.
• make test passes cleanly (both bats specs and tests/sur-*.sh suites).
• pre-commit run --all-files passes (shellcheck, shfmt, conventional-commit, markdownlint if docs touched).

Dependencies / ordering: None. SUR-2503 has no blockers and no sub-issues. It can be started immediately.

---

Risks & Mitigations

#	Risk	Likelihood	Impact	Mitigation
1	The "product change" path requires ECR imagePushedAt field to be present in aws::_describe_findings output; if not, a new ECR describe call may be needed.	Medium	Medium	Before implementing, verify aws ecr describe-image-scan-findings JSON schema includes imagePushedAt. If absent, use aws ecr describe-images instead and introduce a aws::_describe_image helper.
2	Mocking date in bats to control now is fragile if the date mock interferes with other subshell calls.	Low	Low	Use the same pattern already established in the SUR-2477 tests (mock date at the function level via subshell override).
3	If the spec-alignment path is chosen but Linear SUR-2477 cannot be edited (e.g., access issue), the DoD cannot be fully satisfied.	Very low	Low	SUR-2477 is in the same Linear project/team; the same credentials that created SUR-2503 can update SUR-2477.
4	Only 1 Backlog issue means the sprint is extremely narrow. An unexpected complexity spike on SUR-2503 could consume the entire sprint with no fallback work.	Medium	Medium	If SUR-2503 blocks, triage new issues into Backlog (from Triage queue) as contingency work.

---

Out of Scope

• Changes to aws::scan_repository, aws::get_tags, or any other aws.sh functions not directly involved in cache-window logic.
• Changes to aws-get-kubeconfigs.bats or the kubeconfigs command.
• New ECR scanning features beyond closing the SUR-2477 gap.
• Infrastructure or CI workflow changes.
• Documentation of functions other than aws::refresh_scan (unless the spec-alignment path requires @doc annotation updates).

---

Linear Evidence

Field	Value
Linear team verified	Surinis (ID: ce9ebfde-ff2b-4f54-90f1-c388591ca110, key: SUR)
Linear project used	shell-scripts (ID: a43901a0-b02b-4009-aae1-a6e8903d127d)
Query/filter applied	Project = shell-scripts, Team = Surinis, Status = Backlog, includeArchived = false
Backlog issues reviewed	1
Manual-labelled issues skipped	0
Issues skipped — unmerged blockers	0
Issues skipped — open-PR file overlap	0 (OPEN_PR_FILES was empty; Filter B was a no-op)

---

Sub-issue Status

SUR-2503 has no sub-issues. Sub-issue dependency rule does not apply.

---

Linear State Transitions

Issue ID	Previous State	New State
SUR-2503	Backlog	Todo