[Sprint] sprint-loop-46

[scealiontach]

Sprint Plan: 2026-06-08 Sprint Loop 46

Sprint goal

Restore predictable command-line contracts for small, high-priority shell commands by fixing three Backlog bugs where parser or argument handling currently exposes internal behavior instead of documented usage. This sprint intentionally keeps scope reviewable: each selected issue is a focused CLI regression with clear Bats coverage and no active Linear blockers, sub-issue gates, manual label exclusion, or open-PR file overlap.

Selected issues

SUR-3647 - Bug: semver diff missing arguments throw nounset errors instead of usage

Description summary: bash/semver validates arity for bump, compare, and get, but command-diff dereferences $1 and $2 under set -o nounset. bash/semver diff and bash/semver diff 1.2.3 currently fail with raw unbound variable errors instead of usage output. Existing tests/semver.bats coverage exercises valid diff behavior but not invalid arity.

Rationale: This is the smallest, lowest-risk CLI contract fix in the eligible set and gives immediate consistency across semver subcommands.

Definition of Done:

• command-diff rejects zero and one argument before dereferencing positional parameters.
• Missing-argument failures print usage or syntax guidance consistent with adjacent semver subcommands.
• Missing-argument failures do not include unbound variable.
• Existing valid semver diff behavior remains unchanged.
• tests/semver.bats includes regressions for zero and one diff arguments.
• Relevant Bats output is posted back to Linear as verification evidence.

Dependencies / ordering: First. This is independent and establishes the sprint's command-arity pattern.

SUR-3646 - Bug: review-prs bare invocation never reaches default organizations

Description summary: bash/review-prs documents default organization lists for bare invocations, but calls options::parse "$@", which exits with syntax help on no arguments unless NO_SYNTAX_EXIT or options::parse_available is used. As a result, REVIEW_PRS_ORGS and REVIEW_PRS_INTEREST_ORGS defaults are unreachable. Existing tests cover the jq shim but not the command's default path.

Rationale: This is another tight parser behavior fix and can use the repo's documented options::parse_available entry point without changing shared parser semantics.

Definition of Done:

• Bare bash/review-prs reaches the default organization setup path instead of exiting on syntax.
• Explicit -o and -i arguments still work as documented.
• Tests stub gh and jq so the default scan path is verified without network access.
• The regression test proves the default organizations are used on bare invocation.
• Existing jq shim behavior remains covered.
• Relevant Bats output and stubbed bare-invocation evidence are posted back to Linear.

Dependencies / ordering: Second. Independent of SUR-3647, but it should follow the semver arity fix so parser-related test patterns are fresh.

SUR-3645 - Bug: daml-export -h no longer shows standard help

Description summary: bash/daml-export redefines -h as the DAML host option even though options.sh reserves -h for help. daml-export -h is parsed as a missing host argument and can continue into unrelated arithmetic/find errors instead of displaying help. The issue notes bash/daml-export around the host option declaration and bash/options.sh automatic help registration.

Rationale: This completes a coherent parser/help sprint and addresses a user-facing discovery failure in a complex command. It is slightly broader than the first two because the host flag must move to a non-reserved option, so it is ordered last.

Definition of Done:

• bash/daml-export -h displays standard command help.
• The DAML host flag is moved to a non-reserved option such as -H.
• Help text and any docs/test expectations refer to the new host flag.
• The new host flag still populates DAML_HOST correctly.
• The implementation explicitly evaluates duplicate-option detection in options::add; any broader guard is only included if low-risk and covered.
• Tests cover both help behavior and the updated host flag behavior.
• Test output for help and host flag behavior is posted back to Linear.

Dependencies / ordering: Third. It touches a more complex command and may optionally touch shared option registration, so it should wait until the two narrower parser fixes are complete.

Risks + mitigations

• Shared parser behavior can affect many commands if changed globally. Mitigation: prefer command-local fixes for SUR-3646 and SUR-3645 unless duplicate-option detection is demonstrably small and covered by tests/options.bats.
• review-prs normally shells out to gh and jq. Mitigation: test with PATH stubs and avoid network-dependent tests.
• daml-export is a larger script with external DAML/Java assumptions. Mitigation: keep this issue focused on option parsing/help and use isolated command invocations or stubs rather than full export flows.
• Renaming the DAML host flag can surprise existing callers. Mitigation: document the new flag in help/tests and treat backward-compatible aliasing as out of scope unless explicitly added with clear deprecation behavior.
• Verification evidence must not be committed under .claude/sprints/, .claude/runs/, or .claude/plans/. Mitigation: post command output to Linear comments or attach it in Linear only.
• Bats fixtures may need careful HOME/PATH isolation. Mitigation: follow tests/helpers.bash patterns and keep stubs inside test temp directories.

Out of scope

• Kubernetes-related eligible bugs SUR-3648 and SUR-3649.
• The larger DAML export failure handling bug SUR-3644.
• Network-backed review-prs integration testing against real GitHub organizations.
• Broad refactors of options.sh beyond a small duplicate-option guard if it is chosen and covered.
• Capturing verification artifacts in repository-local .claude/ directories.

Linear Evidence

• Linear team verified: Surinis
• Linear project used: shell-scripts
• Query/filter used: Linear MCP list_issues with team=Surinis, project=shell-scripts, state=Backlog, limit=250, then get_issue(includeRelations=true), list_comments, and list_issues(parentId=...) for each candidate.
• 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 []
• Eligible Backlog issues after planner filters: 6
• Candidate comments reviewed: SUR-3644, SUR-3645, SUR-3646, SUR-3647, SUR-3648, SUR-3649; all had no comments returned by Linear.
• Candidate blocked_by relations reviewed: no blockedBy relations returned for any candidate.
• Open-PR file list supplied to planner: []

Sub-issue Status

No reviewed Backlog candidate had sub-issues returned by Linear, so no parent issue was skipped by the sub-issue gate.

Parent Issue	Sub-issue	Sub-issue Status	Eligible?
N/A	N/A	N/A	N/A

Linear State Transitions

Issue ID	Previous State	New State
SUR-3647	Backlog	Todo
SUR-3646	Backlog	Todo
SUR-3645	Backlog	Todo