[Sprint] sprint-loop-29

[scealiontach]

Sprint plan — 2026-04-30 — sprint-loop-29

Sprint goal

Strengthen the SUR-1874 check-no-bare-ret pre-commit hook so its brace-tracking matches real bash structure: nested { ... } groups must not reset “inside function” state, eliminating the false-negative path where a bare ret=$?-style capture after a closing } in a brace group is missed. Align implementation with the hook’s stated enforcement boundary (and the issue’s preferred “option 1” scope) without expanding to a full AST or shellcheck-plugin solution this sprint.

Selected issues

SUR-1936 — Anti-pattern: check-no-bare-ret hook resets state on bare } lines, missing captures inside nested brace groups

• Linear issue ID: SUR-1936
• Title: Anti-pattern: check-no-bare-ret hook resets state on bare } lines, missing captures inside nested brace groups
• Description summary: The hook treats any line that is only } as leaving a function, but bash allows { ... } groups inside functions, so in_function and locals are cleared too early and bare captures of $? after the inner } are not flagged. A secondary fragility is regex-based function detection (name() vs real function defs). File: tests/check-no-bare-ret.sh (lines called out ~38–72). Suggested fixes ordered by effort: (1) track brace depth and only reset when depth returns to zero, (2) shfmt/JSON AST, (3) shellcheck-level rule. Option 1 is explicitly the smallest targeted fix.
• Rationale: Pre-commit hooks that claim a bug class is “impossible to re-introduce” should match that guarantee; the current scanner is structurally loose. Option 1 closes the nested-brace false-negative with minimal churn and keeps the hook dependency-free.
• Definition of Done:
  • Brace depth (or equivalent) is tracked per file scan so an inner } does not clear function context while the outer function body continues.
  • locals / in_function semantics remain correct for existing patterns (function entry/exit, local lines, capture detection).
  • Header/comment claims in tests/check-no-bare-ret.sh are consistent with actual behavior (no overstated guarantees).
  • Automated tests cover at least one nested { ... } fixture where a bare capture after the inner } must be reported, and a control case with local still passes.
  • pre-commit hook check-no-bare-ret still runs successfully on the repo’s bash libraries.
  • No regressions for SUR-1874-related naming (ret, exit_code, exit_status, rc).
• Dependencies / ordering: None (no Linear blockers, no open sub-issues). Implement depth tracking before adjusting any optional follow-up on FUNC_DEF_PAT if time permits.

Risks + mitigations

Risk	Mitigation
Depth counting mishandles } inside strings, comments, or here-docs	Prefer conservative heuristics aligned with issue scope; add fixtures mirroring real bash/ style; extend tests with quoted edge cases if discovered.
False positives on legitimate }-only lines at true function end	Pair depth with function-entry detection so depth 0 + } still exits the function as today.
Regex FUNC_DEF_PAT still brittle for rare name() shapes	Issue defers deeper fixes; document known limits or add one narrow test if changing regex.
Backlog capacity: only one shell-scripts Backlog issue existed at planning time	Single-issue sprint is coherent; next planning cycle should refresh Backlog or pull from Triage when ready.

Out of scope

• Replacing the scanner with shfmt -tojson + jq or a shellcheck plugin (options 2–3 in the issue).
• Changes to unrelated hooks or library SUR-1874 call sites beyond what the hook must scan.
• Issues outside project shell-scripts or team Surinis.

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 team=Surinis, project=shell-scripts, state=Backlog, includeArchived=false, limit=250; per-issue get_issue with includeRelations=true; list_issues with parentId=SUR-1936 for sub-issue check; list_comments on selected issue.
• Approx count of Backlog issues reviewed: 1
• 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 file list was empty)

Sub-issue status

No selected issues have sub-issues in Linear. SUR-1936 has zero child issues; no parent was deferred for incomplete sub-work.

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

Linear state transitions

Issue ID	Previous State	New State
SUR-1936	Backlog	Todo