Review: Enforce backlog→todo review gate hook

Verdict: READY

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- board, story, arch, discovered scope context from PR #213 merge
• [x] Repo -- forgejo_admin/claude-custom
• [x] User Story -- PM wants review gate at backlog-to-todo so TODO always means REVIEWED
• [x] Context -- Lucas correction on kanban semantics, corrected flow diagram included
• [x] File Targets -- 2 files identified with specific change descriptions
• [x] Acceptance Criteria -- 4 testable items
• [x] Test Expectations -- 3 items including manual verification
• [x] Constraints -- 3 constraints (preserve existing gate, naming pattern, verdict check)
• [x] Checklist -- 5 discrete steps
• [x] Related -- 3 references (parent issue, originating PR, behavioral correction)

Traceability

• [x] story:scope-review -- scope review pipeline story, present on board item
• [x] arch:hooks -- hooks architecture component, present on board item
• [x] arch:board-api -- board API architecture component, present on board item
• [x] Forgejo issue -- forgejo_admin/claude-custom#214, open

File Targets

• [x] hooks/check-board-advance.sh -- verified exists at ~/claude-custom/hooks/check-board-advance.sh (194 lines). Currently only gates todo-to-next_up (line 92-95: exits 0 if target column is not next_up). The shared check_review_approved function (lines 46-77) is reusable for the new backlog-to-todo gate without modification. Ticket correctly identifies the gap.
• [x] tests/test_check_board_advance.sh -- verified exists at ~/claude-custom/tests/test_check_board_advance.sh (544 lines, 20 tests). Well-structured mock API server. Existing Test 2 (line 251) explicitly allows "move to todo" without review -- this will need updating for the new gate. Mock data already has items in "todo" column that can be extended to test backlog-to-todo scenarios.

Repo Placement

Dependencies

• [x] Board #364 "Scope review pipeline" (done) -- parent work that created this hook. Satisfied.
• [x] Board #523 "Enforce backlog-first column on create_board_item" (done) -- prerequisite ensuring items start in backlog. Satisfied.
• [x] PR #213 (merged) -- the PR that created check-board-advance.sh. Satisfied.

Acceptance Criteria

• AC1: "blocks backlog-to-todo without APPROVED review note" -- testable via mock API using same pattern as existing Test 11 (deny path). Agent can add mock item in "backlog" column and attempt move to "todo".
• AC2: "Existing todo-to-next_up gate remains functional" -- testable by running existing tests 11-20 unchanged after modifications.
• AC3: "Tests cover both gates" -- verifiable by reviewing test file for both backlog-to-todo AND todo-to-next_up scenarios.
• AC4: "Regression test: backlog-to-todo without review note is blocked" -- testable via mock API, same infrastructure as existing deny tests.

Blast Radius

• settings.json hook matcher (line 191) already covers update_board_item and bulk_move_board_items -- no matcher change needed.
• skill-review-ticket SKILL.md references "check-board-advance hook will now allow the todo -> next_up transition" -- this remains accurate since todo-to-next_up gate is preserved.
• Existing Test 2 ("move to todo -- no gate") will need to become a deny test for backlog-to-todo, but this is correctly scoped within the ticket's test file target.
• No similar ungated transitions found in other hooks. check-board-item.sh handles item creation enforcement, not column transitions.
• Rollback is straightforward -- revert the conditional logic back to next_up-only gating.

Decomposition Assessment

Recommendation