pal-e-docs

Review: Right-side validation pipeline -- /validate-ticket + flow fixes + merge hook

review-518-2026-03-29 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- Companion to #161
  • [x] Repo -- forgejo_admin/claude-custom
  • [x] User Story -- clear "who wants what and why"
  • [x] Context -- thorough, 4-gap analysis with line-level specificity
  • [x] File Targets -- present with create/modify/verify/not-touch sections
  • [x] Acceptance Criteria -- 7 ACs defined
  • [x] Test Expectations -- manual test procedures defined
  • [x] Constraints -- present with 6 constraints
  • [x] Checklist -- present with decomposition tracking
  • [x] Related -- comprehensive cross-references
Template is fully complete. Exemplary feature issue.

Traceability

  • [x] story:pm-scope label -- PM scope management story
  • [x] arch:hooks label -- hooks architecture component
  • [x] arch:board-api label -- board API architecture component
  • [x] Forgejo issue -- forgejo_admin/claude-custom#209, open
All three legs of the traceability triangle are present.

File Targets

  • [x] ~/.claude/hooks/board-item-on-merge.sh -- verified exists. ALREADY FIXED: targets "validation" column (line 132), log messages updated (lines 53, 88, 134, 139). Sub-ticket #227 work is complete.
  • [x] sop-board-workflow flow diagram (block code-11) -- verified. ALREADY FIXED: flow now reads backlog -> todo -> next_up -> in_progress -> qa -> needs_approval -> validation -> done.
  • [ ] agent-workflow flow diagram (block code-13) -- ISSUE: Still reads Forgejo issue -> board (backlog -> todo -> next_up) -> agent -> PR -> QA -> done. Missing needs_approval and validation. Sub-ticket #226 marked done but this target was NOT fixed.
  • [ ] agent-workflow "The Flow" 12-step list (anchor the-flow, block list-21) -- ISSUE: No explicit Validation step between Deploy (step 11) and Update (step 12). Sub-ticket #226 marked done but this was NOT fixed.
  • [ ] ~/.claude/skills/validate-ticket/SKILL.md -- ISSUE: File does NOT exist on the filesystem. Sub-ticket #228 is closed on Forgejo and done on board, but the skill file was never created (or exists on an unmerged branch/worktree).
  • [x] skill-validate-ticket pal-e-docs note (id 841) -- verified exists, active status, well-structured. Pre-satisfied.

Repo Placement

Correct. Issue filed on forgejo_admin/claude-custom which contains hooks and skills. Doc fixes target pal-e-docs notes via MCP (correct for Dottie). No repo mismatch.

Dependencies

  • [x] #161 (left-side scope review pipeline) -- companion issue, in done on board. No blocking dependency.
  • [x] #210 (validation->done gate hook) -- explicitly out of scope, already in done on board. Gate hook gate-validation-done.sh exists and is functional.
  • [ ] Sub-ticket #226 (doc fixes) -- board item 654 in done, Forgejo issue still open. Work INCOMPLETE: sop-board-workflow fixed but agent-workflow NOT fixed.
  • [x] Sub-ticket #227 (merge hook fix) -- board item 655 in done, Forgejo issue open. Work verified complete. Label status:redundant suggests fix predated the ticket.
  • [ ] Sub-ticket #228 (validate-ticket skill) -- board item 656 in done, Forgejo issue closed. But SKILL.md missing from filesystem. Possible lost worktree artifact.
  • [x] validation column in board schema -- verified exists, items are successfully placed in validation column.

Acceptance Criteria

  • [x] AC 1: sop-board-workflow flow diagram includes validation -- PASS, verified in block code-11.
  • [ ] AC 2: agent-workflow board-driven flow includes needs_approval and validation -- FAIL, code-13 still shows QA -> done.
  • [ ] AC 3: agent-workflow "The Flow" 12-step list includes Validation step -- FAIL, no Validation step between Deploy and Update.
  • [x] AC 4: board-item-on-merge.sh moves items to validation -- PASS, verified line 132 targets "validation".
  • [ ] AC 5: /validate-ticket skill exists following review-ticket pattern -- FAIL, SKILL.md not on filesystem.
  • [x] AC 6: skill-validate-ticket note verified current -- PASS, pre-satisfied (note id 841).
  • [ ] AC 7: End-to-end flow works -- CANNOT VERIFY, depends on AC 5.
Score: 3 PASS, 3 FAIL, 1 BLOCKED. Execution is incomplete.

Blast Radius

  • gate-validation-done.sh exists and correctly gates done column moves -- no blast radius concern.
  • No other hooks reference the old "done" target -- the merge hook was the only one that bypassed validation.
  • The stale agent-workflow flow diagram (code-13) is actively misleading agents. Any agent reading the "Work Path: Board-Driven" section sees QA -> done and may skip validation/needs_approval steps. This is a documentation correctness issue with real operational impact.

Decomposition Assessment

This ticket was already decomposed into 3 sub-tickets during a previous review (review-518-2026-03-28). The decomposition structure is sound:
  • Sub-ticket 1 (#226): doc fixes -- Dottie, ~5 min
  • Sub-ticket 2 (#227): merge hook fix -- Dev, ~5 min
  • Sub-ticket 3 (#228): validate-ticket skill -- Dev, ~10-15 min
No further decomposition needed. The 3-ticket structure is correct. The problem is not scope size but incomplete execution: 2 of 3 sub-tickets have deliverables missing despite being marked done. The parent ticket cannot advance to todo until the sub-ticket work is verified and completed.

Recommendation

  • [SCOPE] Sub-ticket #226 needs re-work: agent-workflow code-13 flow diagram and list-21 (12-step list) were not updated. Board item 654 should move back from done. Re-dispatch Dottie to fix the two remaining targets.
  • [SCOPE] Sub-ticket #228 needs investigation: ~/.claude/skills/validate-ticket/SKILL.md is missing from filesystem. Check for unmerged branches or lost worktree artifacts. If lost, re-dispatch Dev to create the skill file. Board item 656 should move back from done until file is confirmed on main.
  • [BODY] Sub-ticket #227: merge hook fix is genuinely complete. Close Forgejo issue #227.
  • [BODY] Update parent issue #209 checklist: mark "Sub-tickets dispatched" as checked. Add AC status summary (3 pass, 3 fail, 1 blocked).
  • [LABEL] No label changes needed on board item #518 -- current labels are accurate.