Review: Scope review pipeline: jidoka for the left side of the board

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- standalone, discovered scope
• [x] Repo -- forgejo_admin/claude-custom
• [x] User Story -- well-formed As/I want/So that
• [x] Context -- excellent detail with TPS analogy and three failure modes
• [x] File Targets -- create and modify lists with NOT-touch list
• [x] Acceptance Criteria -- 7 items
• [x] Test Expectations -- manual tests documented
• [x] Constraints -- patterns, naming conventions, blast radius guards
• [x] Checklist -- standard PR checklist
• [x] Related -- 6 related items linked

Traceability

• [x] story:scope-review label -- user story in issue body
• [x] arch:hooks label -- primary architecture component
• [x] arch:board-api label -- secondary architecture component
• [x] Forgejo issue -- forgejo_admin/claude-custom#161, open

File Targets

• [x] ~/.claude/hooks/check-board-advance.sh -- create target, does not exist yet. Parent directory has 37 hooks. Follows naming pattern. VERIFIED.
• [x] sop-ticket-scope-review pal-e-docs note -- create target, does not exist yet. VERIFIED.
• [ ] ~/.claude/skills/review-ticket/skill.md -- ISSUE: actual file is SKILL.md (uppercase) at ~/claude-custom/skills/review-ticket/SKILL.md. Also unclear whether the review-fix loop belongs in the SKILL.md router or in the pal-e-docs skill-review-ticket agent workflow note (or both).
• [x] ~/.claude/settings.json or settings.local.json -- exists at ~/claude-custom/settings.json. Currently NO mcp__pal-e-docs__update_board_item matcher in PreToolUse. VERIFIED.
• [x] template-ticket pal-e-docs note -- exists with 9 sections. No Review Gate section yet. VERIFIED.
• [x] sop-board-workflow pal-e-docs note -- exists with column-semantics, item-lifecycle. VERIFIED.

Repo Placement

Dependencies

• False constraint reference: Issue says "follow pattern from existing check-board-item.sh" for API querying, but check-board-item.sh does NOT query pal-e-docs API. It only inspects tool_input JSON fields. The new hook would be the FIRST hook to query pal-e-docs from shell -- this is a novel architectural pattern, not an existing one.
• Undocumented dependency: The consolidated spec convention (AC3: refinements UPDATE issue body) requires programmatic Forgejo issue body updates. There is currently no update_issue tool in the Forgejo MCP. Without it, agents must use raw curl. This may be acceptable but should be documented.
• Review note naming convention review-{item_id}-{date} already defined in skill-review-ticket. No conflict.
• No blocking board dependencies found among current in_progress or next_up items.

Acceptance Criteria

• 7 ACs total -- exceeds the 5-AC decomposition threshold
• AC1 (hook blocks update_board_item todo-to-next_up) -- testable but requires novel shell-to-API pattern
• AC2 (review-fix-re-review loop in skill) -- testable via manual invocation
• AC3 (convention: body updates vs comments) -- documentation-only, but programmatic enforcement blocked by missing update_issue MCP tool
• AC4 (SOP note creation) -- verifiable via get_note
• AC5 (template-ticket update) -- verifiable via get_note
• AC6 (end-to-end happy path) -- manual test, complex multi-step
• AC7 (end-to-end block path) -- manual test

Blast Radius

• bulk_move_board_items bypass: The hook targets update_board_item but bulk_move_board_items can also advance items todo-to-next_up. The issue does not mention this tool. A hook on update_board_item alone is incomplete -- bulk_move bypasses the gate.
• First API-calling hook: No existing hook queries pal-e-docs from shell. This introduces a new runtime dependency (API availability, token management, latency). Must fail-open if pal-e-docs is down.
• sync_board safety: session-start-board-sync.sh calls sync_board which may trigger bulk column changes. The new hook must not fire during sync operations.
• No impact on execution pipeline: Hook only gates todo-to-next_up. Other column transitions (in_progress-to-qa, etc.) are unaffected.
• Skill backward compatibility: Existing READY verdicts from skill-review-ticket must still work. Adding review-fix loop logic must be additive.

Decomposition

• 6 file targets across 2 systems (claude-custom filesystem + pal-e-docs API)
• 7 acceptance criteria (exceeds 5-AC threshold)
• Estimated agent work: 15-20 minutes
• Natural split into 3 tickets:

Recommendation

• [BODY] Fix file path case: ~/.claude/skills/review-ticket/skill.md should be SKILL.md (uppercase)
• [BODY] Fix false constraint: "follow pattern from existing check-board-item.sh" -- that hook does NOT query pal-e-docs API. It only validates tool_input fields. The new hook introduces a novel pattern (shell script querying pal-e-docs REST API). Document this as a new architectural pattern.
• [BODY] Add bulk_move_board_items to scope -- either hook it too, or document as known bypass and defer.
• [BODY] Add sync_board safety note -- the hook must not fire during automated sync operations.
• [BODY] Document dependency on update_issue MCP tool (or curl fallback) for AC3 consolidated spec convention.
• [SCOPE] Clarify: should the hook query pal-e-docs via curl (new pattern) or inspect tool_input for a pre-set flag? Curl adds API dependency; input-validation is simpler but requires workflow changes.
• [DECOMPOSE] 7 AC across 2 systems, estimated 15-20 min. Split into 3 tickets via template-board.