pal-e-docs

Review: Validation-gate hook — block done without validation proof (todo→next_up)

review-519-2026-03-28-dispatch Review

review ready
Project

Verdict: READY

This is the todo-to-next_up dispatch gate. The backlog-to-todo review (review-519-2026-03-28, verdict READY) already verified template completeness, file targets, traceability, and dependency status. This review focuses on dispatch readiness: has anything changed, are there blockers, and can an agent execute this in a single pass?

Template Completeness

  • [x] All required Feature sections present (verified in prior review)
  • [x] No sections have been modified or removed since prior review

Traceability

  • [x] story:pm-scope — present on board item
  • [x] arch:hooks — present on board item
  • [x] arch:board-api — present on board item
  • [x] Forgejo issue — forgejo_admin/claude-custom#210, open
No changes. All three legs verified.

File Targets

  • [x] hooks/gate-validation-done.sh (NEW) — confirmed does not exist yet. No branch work started (no 210-* branches found).
  • [x] settings.json — exists. Existing update_board_item matcher at lines 194-201 alongside check-board-advance.sh. No changes since prior review (last commit: ea1e828).
  • [x] hooks/board-item-on-merge.sh — exists. {"column": "done"} at line 132. No changes since prior review.
All file targets stable. No concurrent modifications detected.

Repo Placement

OK. Single repo: forgejo_admin/claude-custom. All targets within.

Dependencies

  • [x] forgejo_admin/pal-e-api#223 (validation BoardColumn) — CLOSED. Board item #480 in done. The board-item-on-merge.sh change to target validation column is now safe with no fallback needed.
  • [x] check-board-advance.sh — no conflicting changes. Line 95 explicitly allows moves to done (exit 0 for non-gated transitions). The new hook gates a different transition (any-to-done). No overlap.
  • [x] No in-progress items on board-pal-e-agency touch the same files. Items #643 (Ava rename) and #478 (note type spike) are in different domains.
  • [x] No existing branches for issue #210.

Acceptance Criteria

6 AC, all testable via shell pipe commands. Test payloads in issue body are realistic. No ambiguous criteria. Agent can verify each one after implementation.

Blast Radius

  • check-board-advance.sh Test 5 ("move to done — no gate") remains correct. The new hook is a separate PreToolUse script; it does not modify check-board-advance behavior.
  • bulk_move_board_items bypass gap noted in prior review. Non-blocking — bulk moves to done are uncommon and can be addressed as discovered scope.
  • commands/update-docs.md line 119 references update_board_item(column="done"). The /update-docs skill will be correctly gated. This is desired behavior.

Decomposition Assessment

3 file targets, 1 repo, 6 AC. Tightly coupled: one new script + registration + one-line fix. Estimated 3-4 minutes. No decomposition needed.

Prior Review Recommendations (status)

  • [BODY] Line reference off-by-one (133 should be 132): not applied to issue body, but harmless — agent will find via grep.
  • [BODY] Settings.json matcher placement: not applied. Agent should add hook to the existing matcher hooks array (lines 194-201) rather than creating a duplicate matcher entry. This is a dispatch note for the agent, not a blocker.

Recommendation

No action needed. Ticket is dispatch-ready. Agent should note the two prior review recommendations (line reference, matcher placement) as implementation guidance but neither blocks dispatch.