feat(incremental): branch-aware residual + scan-worker daemon (#12)

[pureliture]

Summary

Closes the remaining issue #12 gaps on top of the PR #15 queue/worker MVP. Branch becomes a first-class occurrence dimension and per-branch residual is derived (status/disposition stays global).

What

• branch populate: scan_worker tags Finding.repo.branch from ScanJob.ref_name; local_scan reads git HEAD context (_git_head_context); ScanRunSummary.branch recorded.
• observation projection: FINDING_OBSERVATION items carry branch/commit top-level (queryable), not only in findingSnapshot.
• per-branch residual: residual_by_branch / residual_for_repo derived within the REPO#<repo> partition (no new GSI). Matched on commit == last_seen_sha, so a commit at multiple ref tips is residual on every such branch.
• scan-worker --daemon: polling loop with --poll-interval, idle-sleep/drain-fast, SIGINT/SIGTERM graceful shutdown. --once preserved.
• rule_pack invalidation: changing rule_pack_version yields a new ledger key → rescan (verified by test).

Design (locked via grill-to-spec)

• L1 status/disposition GLOBAL (STATE#GLOBAL); branch never enters finding identity (fingerprint).
• L2 residual derived in REPO#<repo> partition; no new GSI.
• L3 evaluate_gate unchanged/global; residual is report/observation visibility only.

Issue #12 criteria

Closes the previously-open 2 (worker polling daemon), 3 (rule_pack invalidation), 6 (per-branch residual end-to-end). Criteria 1/4/5/7 were already met on main.

Deferred (stated)

• Report-generator UI rendering of residual (criterion 6 "확인 가능" met via queryable residual_for_repo).
• GSI sharding for hot-partition at cloud scale (existing TODO, out of Ref update queue + commit ledger 기반 branch-aware scan worker #12 MVP).

Tests

505 → 532 (+27), incl. multi-agent-review fixes: shared-commit residual, daemon dead-letter exit-2, run_local_scan e2e git context. ruff clean on new code.

Refs #12

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces per-branch residual computation for incremental scanning and adds a polling daemon mode (--daemon) to the scan-worker CLI command. It updates both local scans and the scan worker to tag findings with branch and commit context, and extends the DynamoDB store to persist and query these occurrence dimensions. Feedback on the changes highlights three key improvement opportunities: optimizing the residual_by_branch calculation from O(N * M) to O(N + M) using a hash map, avoiding redundant serialization in finding_with_context when no updates are needed, and guarding signal.signal registration in _install_signal_shutdown to prevent runtime errors if executed from a background thread.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[pureliture]

Addressed review feedback in dd39271:

• O(N×M) → indexed observations by commit (O(N+M)) in residual_by_branch
• finding_with_context: short-circuit when commit and branch are both None
• _install_signal_shutdown: skip signal.signal off the main thread
• _ResidualStore Protocol: docstring stubs instead of ... (CodeQL statement-has-no-effect)

Full suite 532 passed; ruff clean on changed code.

[pureliture]

Added in 91faa5b: residual CLI subcommand (per-branch residual visibility, dynamodb-only, mirrors queue-status) — closes the previously-deferred report-UI item for #12 criterion 6. GSI sharding (hot-partition) split to #23. Suite 534 passed.