pal-e-docs

SOP: Board Workflow (Continuous Kanban)

sop-board-workflow Sop

sop active
Project

SOP: Board Workflow (Continuous Kanban)

How work flows through boards. A kanban implements a collection of user story and architecture notes — it is where stories become working software through architecture. Boards are the single source of truth for work status across the enterprise. Continuous flow, not time-boxed sprints. Items flow left to right as work progresses. Sync keeps boards honest.
See convention-kanban-over-plans for the foundational axioms.

Column Semantics

Column Meaning Who Moves Items Here DORA Signal
<code>backlog</code> Unprioritized. Items auto-land here from <code>sync_board</code> and <code>sync-issues</code>. Automated (sync) —
<code>todo</code> Scoped, awaiting review. Ava has triaged. Lucas reviews scope at the <strong>planning review gate</strong> via <code>/review-ticket</code>. Ticket needs READY verdict before advancing. Ava (manual triage) —
<code>next_up</code> Reviewed and approved. Ready to work. Forgejo issue exists, scope verified, agent can be spawned. This is the dispatch queue. Ava (after /review-ticket READY verdict) Lead Time clock starts
<code>in_progress</code> Agent is actively working. Maps to Forgejo label <code>status:in-progress</code> (auto-set by <code>label-on-branch.sh</code>). Automated (label hook on branch creation) Active development time
<code>qa</code> PR submitted, QA review pending. Maps to Forgejo label <code>status:qa</code> (auto-set by <code>label-on-pr.sh</code>). Automated (label hook on PR submission) Code review latency
<code>needs_approval</code> QA approved, awaiting Lucas's merge decision. Maps to Forgejo label <code>status:approved</code>. STOP — never merge without Lucas's approval. Automated (label hook on QA verdict) Approval latency
<code>validation</code> Merged and deployed. Awaiting production validation via <code>/validate-ticket</code>. Validation note required before moving to done. Right-side gate mirroring the left-side review gate at <code>todo</code>. See <code>template-validation</code>. Ava (after merge) Validation latency (merge → PASS)
<code>done</code> Validated in production. Validation note exists with PASS verdict. Lead Time clock stops. Docs updated via <code>/update-docs</code>. Ava (after validation PASS) Lead Time clock stops. Deployment Frequency incremented.
Rework cycle: When QA returns VERDICT: NOT APPROVED, the label-on-verdict.sh hook sets status:needs-fix. The board item moves back to in_progress. Each rework cycle is a Change Failure Rate signal — visible on the board as items bouncing between in_progress and qa.

Sync Cadence

When What How
Session start Sync all active project boards <code>sync_board(board_slug)</code> on each active board. Reconciles Forgejo issues with board items.
Post-merge Move merged item to validation <code>remind-sprint-update.sh</code> fires (Layer 4 reminder).
On-demand Reconcile drift Ava calls <code>sync_board</code> when she suspects drift. Also useful after bulk operations.

Item Lifecycle

How items arrive on boards

Item Type How It Arrives Initial Column
<code>issue</code> Auto via <code>sync-issues</code> — reads open Forgejo issues from linked repos. Or manual via <code>create_board_item</code>. <code>backlog</code> (default for new issues)
<code>incident</code> Manual via <code>create_board_item</code> during incident remediation (see <code>sop-incident-response</code> Step 4). Title describes the <em>fix action</em>, not the incident. Label: <code>type:incident</code>. <code>in_progress</code> (incidents are already being worked when discovered)
<code>repo</code> Manual via <code>create_board_item</code> — for repo onboarding items not auto-synced Specified at creation

How items flow through columns

Left side (backlog → next_up) is the scoping pipeline. Ava owns this. Items move right as they get prioritized and scoped. The left-side gate is the /review-ticket review at todo.
Right side (in_progress → done) is the execution pipeline. Hooks own most transitions. The right-side gate is the validation column — items must pass /validate-ticket before moving to done. See sop-validation and template-validation.
The boundary is next_up → in_progress. This is where Ava spawns an agent and the automation takes over.

Board-to-Label Mapping

The bridge between boards (pal-e-docs) and issues (Forgejo). Labels are the source of truth for execution state; boards reflect that state.
Forgejo Label Board Column Set By
<code>status:in-progress</code> <code>in_progress</code> <code>label-on-branch.sh</code>
<code>status:qa</code> <code>qa</code> <code>label-on-pr.sh</code>
<code>status:needs-fix</code> <code>in_progress</code> <code>label-on-verdict.sh</code>
<code>status:approved</code> <code>needs_approval</code> <code>label-on-verdict.sh</code>
(issue closed / PR merged) <code>validation</code> Post-merge hook

Triage Procedure

Ava reviews boards at session start. The triage flow:
  • Sync — call sync_board on active project boards. New issues auto-appear in backlog.
  • Review backlog — for each new item: is this relevant to current work? Move to todo if yes, leave in backlog if not priority. See template-ticket for what a well-formed item looks like.
  • Scope todo items — scoping requirements depend on item_type: issue items need a Forgejo issue with acceptance criteria and traceability labels (story:, arch:, type:). For all types: add labels. Check WIP limits — if next_up or in_progress columns are at capacity, finish existing work before promoting new items. Check dependencies — are prerequisites completed? If cross-board, check that board.
  • Lucas reviews todo — items in todo are the planning review gate. Lucas reviews scope, acceptance criteria, and technical approach. This mirrors PR code review but for planning. Only after Lucas approves does the item move to next_up.
  • Dispatch next_up — spawn agents for items in next_up per agent-spawn-conventions. Hooks auto-advance from here.
  • Check stuck items — anything in in_progress or qa too long? Investigate. Follow recovery SOPs if needed.

Rules

  • One primary board per project. The board slug is board-{project-slug}. Decomposition boards may exist for large tickets (see template-board).
  • No story points. Flow is measured by cycle time (time in column) and throughput (items done per week). WIP limits on columns control capacity, not point budgets.
  • Issues auto-sync. Open Forgejo issues from linked repos auto-appear as board items. Closed issues move to done on next sync.
  • Don't skip columns. Items flow left to right. The scoping pipeline (backlog → todo → next_up) is manual. The execution pipeline (in_progress → qa → needs_approval → validation → done) is automated with a validation gate before done.
  • Labels are the bridge. Every item has arch: (architecture component), type: (what kind of work), and optionally story: (user story traceability). These are the traceability triangle — see convention-kanban-over-plans.
  • Continuous flow. No sprint boundaries. No kickoff or close ceremonies. No velocity tracking. Work flows when it's ready.
  • Two gates. Left-side gate: /review-ticket at todo (is the scope right?). Right-side gate: /validate-ticket at validation (does it actually work?). Both must pass before items advance.

DORA Integration

Every column transition is a DORA measurement point. The board IS the DORA dashboard:
  • Lead Time for Changes — time from next_up to done. Measured by board item timestamps.
  • Deployment Frequency — rate of items entering done. Only incremented after validation PASS — unvalidated merges do not count.
  • Change Failure Rate — count of needs-fix rework cycles per item (items bouncing between in_progress and qa), plus validation failures (items bouncing from validation back to in_progress).
  • Mean Time to Recovery — for bug/incident items: time from board entry to done. MTTR clock stops at validation PASS, not at merge.
  • Validation Latency — time from merge (entering validation) to validation PASS (entering done). This is the gap between needs_approval and done. Shorter is better. Tracked per item.
  • convention-kanban-over-plans — foundational axioms (kanban purpose, project definition)
  • template-ticket — what a well-formed board item looks like (labels, traceability triangle, lifecycle)
  • template-user-story — user story note format (the WHY leg of the triangle)
  • template-architecture — architecture note format (the WHAT/WHERE leg)
  • pr-lifecycle — the 7-stage PR flow with label integration
  • hook-catalog — enforcement surface map
  • sop-validation — the post-merge validation procedure (right-side gate)
  • template-validation — template for validation evidence notes