Fix Issue

Resolve a reported GitHub issue: understand it, trace to the root cause, fix portably, and lock the fix in with a bats test.

Steps

Pull the issue — gh issue view <number> for title, body, comments. If the user pasted a URL, extract the number from it.
Reproduce — run the failing flow against a fresh fixture (use setup_test_project from tests/test_helper.bash so you don't contaminate the working tree). A bug you can't reproduce is a bug you can't verify fixed.
Trace to the root cause — work outward from the symptom: bin/agentsync.sh (command routing) → lib/sync.sh (per-tool loop) → lib/helpers/*.sh (file ops, YAML parsing, rule merging, format conversion, path safety) → .ai/src/tools/*.yaml. Don't stop at the first plausible cause.
Fix with the smallest correct change — touch only the code that owns the bug. Three similar lines beat a premature abstraction.
Keep it portable — POSIX sed (write-then-mv), cd "$(dirname "$path")" && pwd instead of realpath, quoted "$var", local in functions, set -euo pipefail stays on.
Lint — shellcheck -x -S warning -e SC1091 <changed-scripts>. Resolve warnings; don't paper over with # shellcheck disable=.
Add a bats regression test — fails on main, passes on the fix. Name by behaviour: @test "sync: <what the bug broke> stays correct". Hermetic temp dirs via setup_test_project / teardown_test_project.
Run the full suite — bats tests/. Every test green, not just the new one.
Commit referencing the issue — fix: <subject> (#<issue-number>) so GitHub auto-closes on merge.