ldraney/claude-custom

Fork 0

DECOMPOSED: Right-side validation pipeline — /validate-ticket skill, flow diagrams, merge hook fix #209

New issue

Open

opened 2026-03-28 12:22:00 +00:00 by forgejo_admin · 3 comments

forgejo_admin commented

2026-03-28 12:22:00 +00:00

Contributor

Status: DECOMPOSED

This issue has been decomposed into 3 sub-tickets. Do not dispatch agents against this issue directly.

#226 — Doc fixes (AC 1-3) — Dottie

#227 — Merge hook fix (AC 4) — Dev

#228 — Validate-ticket skill (AC 5, 7) — Dev

See decomposition comment for details.

Type

Feature

Lineage

Companion to forgejo_admin/claude-custom#161 (left-side scope review pipeline). That issue covers backlog→next_up enforcement. This issue covers needs_approval→done enforcement — the right-side mirror.

Discovered during session 2026-03-28 when Betty Sue repeatedly moved items directly to done without validation, and the flow diagram in sop-board-workflow was found to be inconsistent with its own column semantics table.

Repo

forgejo_admin/claude-custom

User Story

As the platform operator
I want the validation pipeline (needs_approval→validation→done) to have the same rigor as the scope review pipeline (todo→next_up)
So that no ticket is marked done without production validation evidence, and DORA Lead Time measurements include validation latency

Context

The validation column was added to sop-board-workflow's Column Semantics table (2026-03-27) along with template-validation. However, four gaps remain:

Flow diagrams are stale. The ASCII flow diagram in sop-board-workflow (anchor: how-items-flow-through-columns, block code-11) shows needs_approval → done with no validation column. The Column Semantics table in the same SOP correctly includes validation. Same SOP, contradictory content. Additionally, agent-workflow (anchor: the-flow-2, block code-13) shows QA → done with no needs_approval or validation.
board-item-on-merge.sh bypasses validation. Lines 54, 89, 134 reference "done" in column target and log/fallback messages. The primary move at line 135 moves items to "done" directly after merge. It should move to "validation" instead. This is the hook that fires on mcp__forgejo__merge_approved_pr. Moving to done without validation makes the validation column dead on arrival.
No /validate-ticket skill exists. The Column Semantics table references /validate-ticket for the validation column, and template-validation documents the note format, but there is no skill to execute validation. The /review-ticket skill (which handles the left-side todo→next_up gate) is the pattern to mirror.
No hook enforcing validation→done gate. There is no equivalent of what #161's check-board-advance.sh would do for the right side. Items can be moved from validation to done without a validation note existing. OUT OF SCOPE — tracked separately as #210.
Betty Sue column-skipping. Without enforcement, Betty Sue put items directly in todo (skipping backlog) and moved items to done (skipping validation) during 2026-03-28 session. The SOP says "don't skip columns" but there's no mechanism preventing it.

File Targets

Files to create:

~/.claude/skills/validate-ticket/SKILL.md — skill that executes production validation for a board item in the validation column, creates a validation note per template-validation, and reports PASS/PARTIAL/FAIL verdict

Files to verify/update (already exists):

pal-e-docs note skill-validate-ticket (id: 841, active) — agent workflow note the skill reads (mirrors skill-review-ticket). Already exists; verify current and update if needed.

Files to modify:

~/.claude/hooks/board-item-on-merge.sh — change target column from "done" to "validation" (line 135), plus update log/fallback messages at lines 54, 89, 134
pal-e-docs note sop-board-workflow — update flow diagram (block code-11) to include validation between needs_approval and done
pal-e-docs note agent-workflow — update flow diagram (block code-13) to include needs_approval and validation
pal-e-docs note agent-workflow — update "The Flow" 12-step list (anchor the-flow) to add validation step between Deploy and Update

Files NOT to touch:

~/.claude/skills/review-ticket/SKILL.md — left-side skill, covered by #161
~/.claude/hooks/check-board-advance.sh — left-side gate hook, covered by #161
Execution pipeline hooks (label-on-branch, label-on-pr, label-on-verdict) — those work fine
template-validation — already complete and well-documented
~/.claude/settings.json or ~/.claude/settings.local.json — validation→done gate hook is OUT OF SCOPE (#210)

Acceptance Criteria

sop-board-workflow flow diagram (block code-11) includes validation between needs_approval and done
agent-workflow board-driven flow (block code-13) includes needs_approval and validation in the pipeline
agent-workflow "The Flow" 12-step list includes a Validation step (between Deploy and Update)
board-item-on-merge.sh moves items to validation column instead of done, and log/fallback messages at lines 54, 89, 134 updated accordingly
/validate-ticket skill exists and follows review-ticket pattern: parse board item, resolve scope, execute validation checks per template-validation, create validation note, report verdict
skill-validate-ticket note verified current in pal-e-docs (pre-satisfied — note id 841 already exists)
End-to-end: merge PR → item auto-moves to validation → run /validate-ticket → PASS → item moves to done

Test Expectations

Manual test: merge a PR → verify board item lands in validation (not done)
Manual test: run /validate-ticket board-slug#item-id on an item in validation → validation note created, verdict reported
Manual test: verify flow diagrams in both SOPs match the Column Semantics table
Run command: manual testing via Claude Code session

Constraints

template-validation already defines the validation note format — the skill must follow it exactly
/validate-ticket must mirror /review-ticket structure: routing skill (SKILL.md) dispatches agent with skill note reference
The board-item-on-merge.sh change includes line 135 (column target) plus lines 54, 89, 134 (log/fallback messages)
validation column must already exist in the board schema (depends on alembic migration adding the column). If the column doesn't exist yet, the merge hook change will fail silently (fail-open pattern). Verify column exists before deploying hook change.
SOP doc updates target specific blocks by anchor ID — use update_block not full note rewrites
Gap 4 (validation→done enforcement hook) is OUT OF SCOPE — tracked separately as #210

Decomposition

DECOMPOSED into 3 sub-tickets (2026-03-28):

#	Ticket	AC	System	Agent	Depends on	~Time
1	#226 Doc fixes — update flow diagrams in sop-board-workflow + agent-workflow	AC 1-3	pal-e-docs	Dottie	none	~5 min
2	#227 Merge hook fix — board-item-on-merge.sh targets validation column	AC 4	shell hook	Dev	none	~5 min
3	#228 Validate-ticket skill — create /validate-ticket SKILL.md	AC 5, 7	skill file	Dev	#226	~10-15 min

AC 6 is pre-satisfied (skill-validate-ticket note already exists, id 841).
Tickets 1 and 2 are independent (parallel dispatch OK). Ticket 3 depends on ticket 1.

Checklist

Scope reviewed (review-518-2026-03-28, NEEDS_REFINEMENT → DECOMPOSE)
Body fixes applied (4 corrections from review)
Decomposed into sub-tickets
Sub-tickets dispatched
All sub-tickets done
End-to-end validation (AC 7)

forgejo_admin/claude-custom#161 — left-side scope review pipeline (companion issue)
forgejo_admin/claude-custom#210 — validation→done gate hook (gap 4, out of scope)
forgejo_admin/claude-custom#226 — sub-ticket 1: doc fixes
forgejo_admin/claude-custom#227 — sub-ticket 2: merge hook fix
forgejo_admin/claude-custom#228 — sub-ticket 3: validate-ticket skill
sop-board-workflow — the SOP with stale flow diagram + correct column semantics table
agent-workflow — the agent workflow note with stale flow diagrams
template-validation — validation note template (already complete)
board-item-on-merge.sh — hook that currently bypasses validation column
review-ticket skill — the left-side skill this mirrors
review-518-2026-03-28 — scope review note

### Status: DECOMPOSED > **This issue has been decomposed into 3 sub-tickets. Do not dispatch agents against this issue directly.** > - #226 — Doc fixes (AC 1-3) — Dottie > - #227 — Merge hook fix (AC 4) — Dev > - #228 — Validate-ticket skill (AC 5, 7) — Dev > > See decomposition comment for details. --- ### Type Feature ### Lineage Companion to `forgejo_admin/claude-custom#161` (left-side scope review pipeline). That issue covers backlog→next_up enforcement. This issue covers needs_approval→done enforcement — the right-side mirror. Discovered during session 2026-03-28 when Betty Sue repeatedly moved items directly to `done` without validation, and the flow diagram in `sop-board-workflow` was found to be inconsistent with its own column semantics table. ### Repo `forgejo_admin/claude-custom` ### User Story As the platform operator I want the validation pipeline (needs_approval→validation→done) to have the same rigor as the scope review pipeline (todo→next_up) So that no ticket is marked done without production validation evidence, and DORA Lead Time measurements include validation latency ### Context The `validation` column was added to `sop-board-workflow`'s Column Semantics table (2026-03-27) along with `template-validation`. However, four gaps remain: 1. **Flow diagrams are stale.** The ASCII flow diagram in `sop-board-workflow` (anchor: `how-items-flow-through-columns`, block `code-11`) shows `needs_approval → done` with no `validation` column. The Column Semantics table in the same SOP correctly includes `validation`. Same SOP, contradictory content. Additionally, `agent-workflow` (anchor: `the-flow-2`, block `code-13`) shows `QA → done` with no `needs_approval` or `validation`. 2. **`board-item-on-merge.sh` bypasses validation.** Lines 54, 89, 134 reference `"done"` in column target and log/fallback messages. The primary move at line 135 moves items to `"done"` directly after merge. It should move to `"validation"` instead. This is the hook that fires on `mcp__forgejo__merge_approved_pr`. Moving to `done` without validation makes the `validation` column dead on arrival. 3. **No `/validate-ticket` skill exists.** The Column Semantics table references `/validate-ticket` for the `validation` column, and `template-validation` documents the note format, but there is no skill to execute validation. The `/review-ticket` skill (which handles the left-side `todo→next_up` gate) is the pattern to mirror. 4. **No hook enforcing validation→done gate.** There is no equivalent of what #161's `check-board-advance.sh` would do for the right side. Items can be moved from `validation` to `done` without a validation note existing. **OUT OF SCOPE — tracked separately as #210.** 5. **Betty Sue column-skipping.** Without enforcement, Betty Sue put items directly in `todo` (skipping `backlog`) and moved items to `done` (skipping `validation`) during 2026-03-28 session. The SOP says "don't skip columns" but there's no mechanism preventing it. ### File Targets Files to create: - `~/.claude/skills/validate-ticket/SKILL.md` — skill that executes production validation for a board item in the `validation` column, creates a validation note per `template-validation`, and reports PASS/PARTIAL/FAIL verdict Files to verify/update (already exists): - pal-e-docs note `skill-validate-ticket` (id: 841, active) — agent workflow note the skill reads (mirrors `skill-review-ticket`). Already exists; verify current and update if needed. Files to modify: - `~/.claude/hooks/board-item-on-merge.sh` — change target column from `"done"` to `"validation"` (line 135), plus update log/fallback messages at lines 54, 89, 134 - pal-e-docs note `sop-board-workflow` — update flow diagram (block `code-11`) to include `validation` between `needs_approval` and `done` - pal-e-docs note `agent-workflow` — update flow diagram (block `code-13`) to include `needs_approval` and `validation` - pal-e-docs note `agent-workflow` — update "The Flow" 12-step list (anchor `the-flow`) to add validation step between Deploy and Update Files NOT to touch: - `~/.claude/skills/review-ticket/SKILL.md` — left-side skill, covered by #161 - `~/.claude/hooks/check-board-advance.sh` — left-side gate hook, covered by #161 - Execution pipeline hooks (label-on-branch, label-on-pr, label-on-verdict) — those work fine - `template-validation` — already complete and well-documented - `~/.claude/settings.json` or `~/.claude/settings.local.json` — validation→done gate hook is OUT OF SCOPE (#210) ### Acceptance Criteria - [ ] `sop-board-workflow` flow diagram (block `code-11`) includes `validation` between `needs_approval` and `done` - [ ] `agent-workflow` board-driven flow (block `code-13`) includes `needs_approval` and `validation` in the pipeline - [ ] `agent-workflow` "The Flow" 12-step list includes a Validation step (between Deploy and Update) - [ ] `board-item-on-merge.sh` moves items to `validation` column instead of `done`, and log/fallback messages at lines 54, 89, 134 updated accordingly - [ ] `/validate-ticket` skill exists and follows `review-ticket` pattern: parse board item, resolve scope, execute validation checks per `template-validation`, create validation note, report verdict - [ ] `skill-validate-ticket` note verified current in pal-e-docs (pre-satisfied — note id 841 already exists) - [ ] End-to-end: merge PR → item auto-moves to `validation` → run `/validate-ticket` → PASS → item moves to `done` ### Test Expectations - [ ] Manual test: merge a PR → verify board item lands in `validation` (not `done`) - [ ] Manual test: run `/validate-ticket board-slug#item-id` on an item in `validation` → validation note created, verdict reported - [ ] Manual test: verify flow diagrams in both SOPs match the Column Semantics table - Run command: manual testing via Claude Code session ### Constraints - `template-validation` already defines the validation note format — the skill must follow it exactly - `/validate-ticket` must mirror `/review-ticket` structure: routing skill (SKILL.md) dispatches agent with skill note reference - The `board-item-on-merge.sh` change includes line 135 (column target) plus lines 54, 89, 134 (log/fallback messages) - `validation` column must already exist in the board schema (depends on alembic migration adding the column). If the column doesn't exist yet, the merge hook change will fail silently (fail-open pattern). Verify column exists before deploying hook change. - SOP doc updates target specific blocks by anchor ID — use `update_block` not full note rewrites - Gap 4 (validation→done enforcement hook) is OUT OF SCOPE — tracked separately as #210 ### Decomposition **DECOMPOSED into 3 sub-tickets (2026-03-28):** | # | Ticket | AC | System | Agent | Depends on | ~Time | |---|--------|----|--------|-------|------------|-------| | 1 | #226 Doc fixes — update flow diagrams in sop-board-workflow + agent-workflow | AC 1-3 | pal-e-docs | Dottie | none | ~5 min | | 2 | #227 Merge hook fix — board-item-on-merge.sh targets validation column | AC 4 | shell hook | Dev | none | ~5 min | | 3 | #228 Validate-ticket skill — create /validate-ticket SKILL.md | AC 5, 7 | skill file | Dev | #226 | ~10-15 min | AC 6 is pre-satisfied (`skill-validate-ticket` note already exists, id 841). Tickets 1 and 2 are independent (parallel dispatch OK). Ticket 3 depends on ticket 1. ### Checklist - [x] Scope reviewed (review-518-2026-03-28, NEEDS_REFINEMENT → DECOMPOSE) - [x] Body fixes applied (4 corrections from review) - [x] Decomposed into sub-tickets - [ ] Sub-tickets dispatched - [ ] All sub-tickets done - [ ] End-to-end validation (AC 7) ### Related - `forgejo_admin/claude-custom#161` — left-side scope review pipeline (companion issue) - `forgejo_admin/claude-custom#210` — validation→done gate hook (gap 4, out of scope) - `forgejo_admin/claude-custom#226` — sub-ticket 1: doc fixes - `forgejo_admin/claude-custom#227` — sub-ticket 2: merge hook fix - `forgejo_admin/claude-custom#228` — sub-ticket 3: validate-ticket skill - `sop-board-workflow` — the SOP with stale flow diagram + correct column semantics table - `agent-workflow` — the agent workflow note with stale flow diagrams - `template-validation` — validation note template (already complete) - `board-item-on-merge.sh` — hook that currently bypasses validation column - `review-ticket` skill — the left-side skill this mirrors - `review-518-2026-03-28` — scope review note

forgejo_admin commented

2026-03-29 04:19:42 +00:00

Author

Contributor

Scope Review: NEEDS_REFINEMENT

Review note: review-518-2026-03-28
Ticket is well-scoped but has 4 body fixes needed and requires decomposition before execution.

skill-validate-ticket note already exists (id: 841) — AC 6 is pre-satisfied, file target says "create" but should say "verify/update"
Lines 54, 89, 134 of board-item-on-merge.sh also reference "done" in log/fallback messages — not listed in file targets
Gap 4 (validation→done enforcement hook) is mentioned in Context but absent from AC and Decomposition — relationship to board item #519 needs explicit statement
AC 6 should be removed or rephrased since it is already satisfied
Recommend decomposition via template-board — 7 AC across 3 systems (docs, hooks, skills)

## Scope Review: NEEDS_REFINEMENT Review note: `review-518-2026-03-28` Ticket is well-scoped but has 4 body fixes needed and requires decomposition before execution. - `skill-validate-ticket` note already exists (id: 841) — AC 6 is pre-satisfied, file target says "create" but should say "verify/update" - Lines 54, 89, 134 of `board-item-on-merge.sh` also reference "done" in log/fallback messages — not listed in file targets - Gap 4 (validation→done enforcement hook) is mentioned in Context but absent from AC and Decomposition — relationship to board item #519 needs explicit statement - AC 6 should be removed or rephrased since it is already satisfied - Recommend decomposition via template-board — 7 AC across 3 systems (docs, hooks, skills)

forgejo_admin changed title from ~~Feature: Right-side validation pipeline — /validate-ticket skill, flow diagrams, merge hook fix~~ to DECOMPOSED: Right-side validation pipeline — /validate-ticket skill, flow diagrams, merge hook fix

2026-03-29 04:25:50 +00:00

forgejo_admin referenced this issue

2026-03-29 04:26:09 +00:00

Doc fixes: update validation flow diagrams in sop-board-workflow + agent-workflow #226

forgejo_admin referenced this issue

2026-03-29 04:26:19 +00:00

Merge hook fix: board-item-on-merge.sh targets validation column #227

forgejo_admin referenced this issue

2026-03-29 04:26:35 +00:00

Create /validate-ticket skill mirroring /review-ticket pattern #228

forgejo_admin commented

2026-03-29 04:29:14 +00:00

Author

Contributor

Decomposition Complete

Review: review-518-2026-03-28 (verdict: NEEDS_REFINEMENT, action: DECOMPOSE)

Body Fixes Applied (4)

skill-validate-ticket note already exists (id 841) — changed "create" to "verify/update" in File Targets, rephrased AC 6 as pre-satisfied
Added lines 54, 89, 134 to merge hook file targets (log/fallback messages referencing "done")
Clarified Gap 4 (validation→done enforcement hook) as OUT OF SCOPE — tracked separately as #210
Removed settings.json from file targets (gate hook is #210 scope, not this issue)

3-Ticket Split

Sub-ticket	Board Item	AC	System	Agent	Depends on	~Time
#226 Doc fixes: flow diagrams	#654	AC 1-3	pal-e-docs	Dottie	none	~5 min
#227 Merge hook fix	#655	AC 4	shell hook	Dev	none	~5 min
#228 Validate-ticket skill	#656	AC 5, 7	skill file	Dev	#226	~10-15 min

AC 6 is pre-satisfied (skill-validate-ticket note id 841 already exists)
#226 and #227 are independent (parallel dispatch OK)
#228 depends on #226 (docs must exist before skill references them)
All 3 items placed in backlog on board-pal-e-agency with story:pm-scope + parent:#209

Executed by: Dottie (doc librarian agent)

## Decomposition Complete **Review:** `review-518-2026-03-28` (verdict: NEEDS_REFINEMENT, action: DECOMPOSE) ### Body Fixes Applied (4) 1. `skill-validate-ticket` note already exists (id 841) — changed "create" to "verify/update" in File Targets, rephrased AC 6 as pre-satisfied 2. Added lines 54, 89, 134 to merge hook file targets (log/fallback messages referencing "done") 3. Clarified Gap 4 (validation→done enforcement hook) as OUT OF SCOPE — tracked separately as #210 4. Removed `settings.json` from file targets (gate hook is #210 scope, not this issue) ### 3-Ticket Split | Sub-ticket | Board Item | AC | System | Agent | Depends on | ~Time | |---|---|---|---|---|---|---| | #226 Doc fixes: flow diagrams | #654 | AC 1-3 | pal-e-docs | Dottie | none | ~5 min | | #227 Merge hook fix | #655 | AC 4 | shell hook | Dev | none | ~5 min | | #228 Validate-ticket skill | #656 | AC 5, 7 | skill file | Dev | #226 | ~10-15 min | - AC 6 is pre-satisfied (`skill-validate-ticket` note id 841 already exists) - #226 and #227 are independent (parallel dispatch OK) - #228 depends on #226 (docs must exist before skill references them) - All 3 items placed in `backlog` on `board-pal-e-agency` with `story:pm-scope` + `parent:#209` **Executed by:** Dottie (doc librarian agent)

forgejo_admin referenced this issue

2026-03-29 04:29:54 +00:00

Merge hook fix: board-item-on-merge.sh targets validation column #227

forgejo_admin referenced this issue

2026-03-29 04:36:49 +00:00

feat: add /validate-ticket skill for post-merge validation #230

forgejo_admin referenced this issue

2026-03-29 04:39:22 +00:00

feat: add /validate-ticket skill for post-merge validation #230

forgejo_admin commented

2026-03-29 19:01:12 +00:00

Author

Contributor

Scope Review: NEEDS_REFINEMENT

Review note: review-518-2026-03-29
Execution is incomplete -- 3 of 7 ACs pass, 3 fail, 1 blocked. Sub-tickets were decomposed correctly but deliverables are missing.

#226 (doc fixes): sop-board-workflow code-11 was fixed, but agent-workflow code-13 flow diagram and list-21 (12-step list) were NOT updated. Board item shows done but work is incomplete.
#228 (validate-ticket skill): ~/.claude/skills/validate-ticket/SKILL.md does not exist on filesystem despite sub-ticket being closed. Possible lost worktree artifact.
#227 (merge hook): Verified complete. board-item-on-merge.sh correctly targets validation column.

Recommend: re-dispatch #226 for remaining doc targets, investigate #228 for missing SKILL.md file.

## Scope Review: NEEDS_REFINEMENT Review note: `review-518-2026-03-29` Execution is incomplete -- 3 of 7 ACs pass, 3 fail, 1 blocked. Sub-tickets were decomposed correctly but deliverables are missing. - **#226 (doc fixes):** `sop-board-workflow` code-11 was fixed, but `agent-workflow` code-13 flow diagram and list-21 (12-step list) were NOT updated. Board item shows done but work is incomplete. - **#228 (validate-ticket skill):** `~/.claude/skills/validate-ticket/SKILL.md` does not exist on filesystem despite sub-ticket being closed. Possible lost worktree artifact. - **#227 (merge hook):** Verified complete. `board-item-on-merge.sh` correctly targets `validation` column. Recommend: re-dispatch #226 for remaining doc targets, investigate #228 for missing SKILL.md file.

forgejo_admin referenced this issue

2026-03-29 19:25:07 +00:00

Create /validate-ticket SKILL.md (lost from #228) #231