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

New issue

Open

opened 2026-03-29 04:26:09 +00:00 by forgejo_admin · 0 comments

forgejo_admin commented

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

Contributor

Type

Story (sub-ticket of #209)

Lineage

Parent: #209 (right-side validation pipeline)
Sub-ticket 1 of 3. Independent — can be dispatched in parallel with #227.

Repo

forgejo_admin/claude-custom (but all changes are in pal-e-docs, not code files)

User Story

As the platform operator
I want the flow diagrams in sop-board-workflow and agent-workflow to include the validation column
So that the documented pipeline matches the actual column semantics and agents follow the correct flow

Context

The validation column was added to sop-board-workflow's Column Semantics table (2026-03-27) but the flow diagrams were never updated. Three specific blocks are stale:

sop-board-workflow block code-11 (anchor: how-items-flow-through-columns) — shows needs_approval → done with no validation
agent-workflow block code-13 (anchor: the-flow-2) — shows QA → done with no needs_approval or validation
agent-workflow block list-21 (anchor: the-flow) — 12-step list goes Deploy (11) → Update (12) with no Validation step

File Targets

Files to modify (all via pal-e-docs update_block MCP tool):

sop-board-workflow block code-11 — add validation between needs_approval and done in ASCII flow diagram
agent-workflow block code-13 — add needs_approval and validation to the pipeline flow diagram
agent-workflow block list-21 — add Validation step between Deploy (step 11) and Update (step 12), renumbering as needed

Files NOT to touch:

template-validation — already complete
sop-board-workflow Column Semantics table — already correct
Any code files — this is docs-only

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" step list (block list-21) includes a Validation step between Deploy and Update

Test Expectations

Read updated blocks via get_section and verify validation appears in each
Verify flow diagram column order matches Column Semantics table in sop-board-workflow
Run command: manual verification via MCP tools

Constraints

Use update_block for targeted block edits — do NOT rewrite full notes
Read each block BEFORE editing to get current content
The Column Semantics table in sop-board-workflow is the source of truth for column order
Agent: Dottie (doc librarian)

Checklist

PR opened (N/A — pal-e-docs changes, no PR needed)
Changes verified via MCP read-back
No unrelated changes

#209 — parent issue (DECOMPOSED)
#227 — sibling: merge hook fix (parallel)
#228 — sibling: validate-ticket skill (depends on this ticket)
sop-board-workflow — SOP with stale flow diagram
agent-workflow — agent workflow with stale flow diagrams
review-518-2026-03-28 — scope review that identified these gaps

### Type Story (sub-ticket of #209) ### Lineage Parent: #209 (right-side validation pipeline) Sub-ticket 1 of 3. Independent — can be dispatched in parallel with #227. ### Repo `forgejo_admin/claude-custom` (but all changes are in pal-e-docs, not code files) ### User Story As the platform operator I want the flow diagrams in `sop-board-workflow` and `agent-workflow` to include the `validation` column So that the documented pipeline matches the actual column semantics and agents follow the correct flow ### Context The `validation` column was added to `sop-board-workflow`'s Column Semantics table (2026-03-27) but the flow diagrams were never updated. Three specific blocks are stale: 1. `sop-board-workflow` block `code-11` (anchor: `how-items-flow-through-columns`) — shows `needs_approval → done` with no `validation` 2. `agent-workflow` block `code-13` (anchor: `the-flow-2`) — shows `QA → done` with no `needs_approval` or `validation` 3. `agent-workflow` block `list-21` (anchor: `the-flow`) — 12-step list goes Deploy (11) → Update (12) with no Validation step ### File Targets Files to modify (all via pal-e-docs `update_block` MCP tool): - `sop-board-workflow` block `code-11` — add `validation` between `needs_approval` and `done` in ASCII flow diagram - `agent-workflow` block `code-13` — add `needs_approval` and `validation` to the pipeline flow diagram - `agent-workflow` block `list-21` — add Validation step between Deploy (step 11) and Update (step 12), renumbering as needed Files NOT to touch: - `template-validation` — already complete - `sop-board-workflow` Column Semantics table — already correct - Any code files — this is docs-only ### 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" step list (block `list-21`) includes a Validation step between Deploy and Update ### Test Expectations - [ ] Read updated blocks via `get_section` and verify `validation` appears in each - [ ] Verify flow diagram column order matches Column Semantics table in `sop-board-workflow` - Run command: manual verification via MCP tools ### Constraints - Use `update_block` for targeted block edits — do NOT rewrite full notes - Read each block BEFORE editing to get current content - The Column Semantics table in `sop-board-workflow` is the source of truth for column order - Agent: Dottie (doc librarian) ### Checklist - [ ] PR opened (N/A — pal-e-docs changes, no PR needed) - [ ] Changes verified via MCP read-back - [ ] No unrelated changes ### Related - #209 — parent issue (DECOMPOSED) - #227 — sibling: merge hook fix (parallel) - #228 — sibling: validate-ticket skill (depends on this ticket) - `sop-board-workflow` — SOP with stale flow diagram - `agent-workflow` — agent workflow with stale flow diagrams - `review-518-2026-03-28` — scope review that identified these gaps