[scealiontach]

Sprint Plan — sprint-loop-21 (2026-04-29)

Sprint Goal

Close out the three deferred sprint-loop-20 follow-up items that were explicitly
carried forward when PR #18 merged. Fix the variable-scoping and process-substitution
bug in bash/daml-export (SUR-1888, High priority) that was never implemented in
loop-20, and add the four missing bats test specs for bash/exec.sh, bash/docker.sh,
bash/clean-branches, and bash/git-check (SUR-1889, SUR-1890, Medium priority)
that were similarly deferred. By the end of this sprint the full test suite pinned by
the loop-20 follow-ups will be green, the daml-export process-substitution invariant
will be verified, and the regression gaps identified after PR #18 will be closed.

---

Selected Issues

SUR-1888 — Bug: daml-export bare ret=$? in post-loop block

Field	Value
Linear ID	SUR-1888
Priority	High (2)
Status	Backlog → Todo

Description Summary

Follow-up to SUR-1883 (itself a follow-up to SUR-1871). PR #18 in sprint-loop-20
contained no changes to bash/daml-export or tests/sur-1871-daml-export.sh, so
all four acceptance criteria from SUR-1883 remain outstanding:

1. No bare ret=$? anywhere in bash/daml-export; every site uses local ret=$?
   inside a function body, or is rewritten to if cmd; then / if ! cmd; then.
2. The post-loop find … -name export.good walk uses process substitution
   < <(...) (or equivalent non-subshell construct) so that RUNNING_PROCS
   mutations reach the parent shell.
3. tests/sur-1871-daml-export.sh continues to pass and is extended to assert
   that RUNNING_PROCS reflects the builds triggered during the post-loop walk.
4. pre-commit run --files bash/daml-export exits 0.

The issue provides a complete suggested refactor: extract the post-loop body into a
named verify_and_build function and feed the find results via < <(...).

Rationale

Highest priority issue in the Backlog (High/2). The bug silently discards
RUNNING_PROCS mutations because the find pipe runs in a subshell — a correctness
defect, not merely a style issue. The fix is fully specified in the issue description
with a concrete code sample. Addressing it first unblocks the test extension work.

Definition of Done

• No bare ret=$? in bash/daml-export (all uses are local ret=$? inside
  function bodies or replaced with if cmd; then / if ! cmd; then form)
• Post-loop find … -name export.good walk uses process substitution < <(…),
  ensuring RUNNING_PROCS mutations are visible in the parent shell
• tests/sur-1871-daml-export.sh passes and asserts RUNNING_PROCS is populated
  after the post-loop walk completes
• pre-commit run --files bash/daml-export exits 0 (shellcheck + shfmt clean)
• make test passes with no regressions

Dependencies / Ordering

Independent of SUR-1889 and SUR-1890. Implement first (highest priority).

---

SUR-1889 — Test: missing bats coverage for bash/exec.sh and bash/docker.sh

Field	Value
Linear ID	SUR-1889
Priority	Medium (3)
Status	Backlog → Todo

Description Summary

Partial follow-up to SUR-1881. PR #18 added five of the seven library specs; two
DoD items remain unimplemented:

• tests/exec.bats: assert exec_code is not leaked into calling scope; assert
  exec::hide swallows stdout/stderr but preserves exit codes; assert
  exec::capture captures output to $exec_output with exit code preserved;
  assert deprecated shims exec_and_hide / exec_and_capture delegate correctly.
• tests/docker.bats: stub docker via a fake-PATH binary; assert docker::cp
  returns 1 for pull failure, 2 for tag failure, 3 for push failure; assert 0 on
  full success.

Each spec must use helpers::isolate_home in setup(), stub externals via a
fake-PATH directory prepended in setup, cover the public API and deprecated shims,
and pass under make test_bats without modification.

Reference patterns: tests/secret.bats (EXIT-trap/subshell isolation),
tests/annotations.bats (deprecated-shim forwarding), tests/k8s.bats
(fake-PATH stub binaries).

Rationale

Closes the final two library spec gaps from SUR-1881. Both specs follow patterns
already established and merged in PR #18, making them low-risk and fully automatable.

Definition of Done

• tests/exec.bats exists and covers: exec_code scoping, exec::hide
  stdout/stderr suppression with exit-code preservation, exec::capture output
  capture, deprecated shims exec_and_hide / exec_and_capture
• tests/docker.bats exists and covers: docker::cp returning 1/2/3 for
  pull/tag/push failures and 0 for full success
• Both specs call helpers::isolate_home in setup()
• External binaries stubbed via fake-PATH directory prepended in setup
• make test_bats passes

Dependencies / Ordering

Independent of SUR-1888 and SUR-1890. Can run in parallel with SUR-1890 after
SUR-1888 is complete (or concurrently if separate branches are used).

---

SUR-1890 — Test: missing bats coverage for clean-branches and git-check command scripts

Field	Value
Linear ID	SUR-1890
Priority	Medium (3)
Status	Backlog → Todo

Description Summary

Partial follow-up to SUR-1882. PR #18 added five of the seven DoD items; two remain:

• tests/clean-branches.bats: use helpers::make_fixture_repo to create a fixture
  repo with several local branches and a build/1.0 tag. Assert that dry-run mode
  does NOT delete any branches. Assert that -T flag deletes only build/* tags
  and leaves other tags untouched. Pins the SUR-1835 dry-run invariant.
• tests/git-check.bats: use helpers::make_fixture_repo to create fixture repos
  representing UNCOMMITTED, RELEASABLE, and DEVELOPMENT states. Assert that the
  bucketing output from bash/git-check is correct for each state. Locks the
  SUR-1857 fix.

Both specs must pass under make test_bats. Reference patterns: tests/changelog.bats
for branch/tag manipulation in fixtures, tests/pretty-labels.bats for stubbing
kubectl-style external tools.

Rationale

Closes the final two command-script spec gaps from SUR-1882. The
helpers::make_fixture_repo helper required to implement both specs was already
added in PR #18, making this work unblocked and fully automatable.

Definition of Done

• tests/clean-branches.bats exists and tests: dry-run does not delete branches,
  -T flag deletes only build/* tags and leaves other tags untouched
• tests/git-check.bats exists and tests: correct bucketing output for
  UNCOMMITTED, RELEASABLE, and DEVELOPMENT fixture states
• Both specs use helpers::make_fixture_repo (available from PR [Sprint] sprint-loop-20 #18 merge)
• Reference patterns from tests/changelog.bats and tests/pretty-labels.bats
  followed for branch/tag manipulation and stubbing respectively
• make test_bats passes

Dependencies / Ordering

Independent of SUR-1888 and SUR-1889. Can run in parallel with SUR-1889.

---

Risks and Mitigations

#	Risk	Likelihood	Impact	Mitigation
1	bash/daml-export has bare ret=$? outside a function body where local is invalid	Medium	Medium	Use if cmd; then / if ! cmd; then form at those sites instead of local ret=$?; the issue description pre-identifies all sites
2	verify_and_build refactor alters behaviour if RUNNING_PROCS=("${RUNNING_PROCS[@]}") compaction order changes	Low	High	Pin regression with explicit assertions on array length after wait -n in the extended test; compare output vs the unrefactored baseline
3	Fake-PATH docker stub in tests/docker.bats shadowed by real docker on PATH	Low	Medium	Prepend the fake-PATH directory unconditionally in setup(); verify in teardown that the real binary is restored
4	helpers::make_fixture_repo may not natively create UNCOMMITTED state for git-check tests	Low	Low	Fall back to manual git init + unstaged-change setup steps in the spec if needed; DEVELOPMENT state can be approximated similarly
5	shellcheck flags new code in daml-export refactor (e.g. SC2155 on local ret)	Medium	Low	Run pre-commit run --files bash/daml-export after each edit; fix inline before committing
6	make test_bats submodule not initialised on a fresh checkout	Low	Medium	Document git submodule update --init as a prerequisite in the verification plan

---

Out of Scope

• Implementing any part of parent issues SUR-1881, SUR-1882, SUR-1883 beyond the
  specific items carried in SUR-1889, SUR-1890, and SUR-1888 respectively
• Any new features or libraries not mentioned in the selected issues
• CHANGELOG.md updates (handled automatically by the release process via
  bash/update-repo-tags)
• CI workflow changes
• Changes to any file not listed in the Implementation Plan

---

Linear Evidence

Field	Value
Linear team verified	Surinis (ID: ce9ebfde-ff2b-4f54-90f1-c388591ca110)
Linear project used	shell-scripts (ID: a43901a0-b02b-4009-aae1-a6e8903d127d)
Query / filter used	list_issues project=shell-scripts state=Backlog limit=250
Approx Backlog issues reviewed	3
Manual-labelled Backlog issues skipped	0

---

Sub-issue Status

No issue selected for this sprint has sub-issues. The sub-issue dependency rule
was checked for all three candidates (SUR-1888, SUR-1889, SUR-1890) via
list_issues parentId=<id> calls; all returned empty results. The table below
is intentionally empty — its absence is deliberate, not an omission.

Parent Issue	Sub-issue	Sub-issue Status	Eligible?
—	—	—	—

---

Linear State Transitions

Issue ID	Previous State	New State
SUR-1888	Backlog	Todo
SUR-1889	Backlog	Todo
SUR-1890	Backlog	Todo