# Phase 9: Etapes - Context

**Gathered:** 2026-05-15
**Status:** Ready for planning

<domain>
## Phase Boundary

Phase 9 delivers one-level etapes inside a tablo so users can organize tasks under optional parent wrappers without breaking the current kanban model. Users can create, edit, delete, and reorder etapes; assign each task to zero or one etape; filter the existing kanban by etape; and delete an etape without deleting its tasks.

</domain>

<decisions>
## Implementation Decisions

### Etape Surface
- **D-01:** Etapes should live in a compact top strip above the existing task kanban in the Tasks tab.
- **D-02:** The strip should use compact etape chips with task counts.
- **D-03:** The strip should include an `Unassigned` chip for tasks with no etape.
- **D-04:** The first version should keep etape controls functional and simple; polished visual design is deferred until the user provides a later UI pass.

### Task Grouping Behavior
- **D-05:** Selecting an etape should filter the existing kanban to tasks assigned to that etape.
- **D-06:** Selecting `Unassigned` should filter the kanban to tasks without an etape.
- **D-07:** The kanban's four status columns remain the core task layout; etapes must not become primary swimlanes or nested status groups in this phase.

### Ordering Model
- **D-08:** Etapes have their own independent order via an etape position field.
- **D-09:** Task ordering remains scoped by the current tablo/status/position model. Do not scope task position by etape in Phase 9.
- **D-10:** Existing drag/drop semantics must continue to work across kanban statuses after etape support is added.

### Assignment Workflow
- **D-11:** Task create and edit forms should include an etape selector.
- **D-12:** A task may be assigned to zero or one etape.
- **D-13:** Quick assignment dropdowns on task cards are not required for the first functional version.

### Delete Behavior And Data Shape
- **D-14:** Deleting an etape unassigns its tasks by default and must not delete those tasks.
- **D-15:** Nested etapes are out of scope. Model etapes as a separate table owned by a tablo, and model tasks as optional children via a nullable etape reference.
- **D-16:** The schema should make nesting impossible rather than relying on UI restrictions.

### Agent Discretion
- The planner may choose exact route names, query names, and HTMX fragment boundaries if they preserve the decisions above and follow existing local patterns.

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Product Scope
- `.planning/ROADMAP.md` - Phase 9 goal, success criteria, user-in-loop checkpoint, and MVP mode.
- `.planning/REQUIREMENTS.md` - ETAPE-01 through ETAPE-06 and deferred future etape ideas.

### Existing Task/Kanban Implementation
- `backend/migrations/0004_tasks.sql` - current task schema, `task_status` enum order, and `tasks_tablo_id_status_idx` index.
- `backend/internal/db/queries/tasks.sql` - current task list/create/update/delete/reorder query surface.
- `backend/templates/tasks.templ` - existing kanban board, task cards, inline create/edit forms, and Sortable.js reorder behavior.
- `backend/templates/tablos.templ` - Tasks tab fragment integration point.
- `backend/internal/web/handlers_tasks.go` - task handlers, ownership checks, create/update/delete/reorder behavior.
- `backend/internal/web/handlers_tasks_test.go` - existing task behavior coverage that Phase 9 must preserve and extend.
- `backend/internal/web/router.go` - current task route mounting pattern.

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `templates.KanbanBoard` renders a flat task slice grouped by status. Phase 9 should extend this surface with etape filter context rather than replacing the board.
- `templates.TaskCreateFormFragment` and `templates.TaskEditFragment` are the natural places to add the etape selector.
- `loadOwnedTablo` and `loadOwnedTabloForTask` already enforce ownership for tablo/task routes and should guide etape handler authorization.
- `TaskColumns` and `TaskColumnLabels` define the canonical status column order and should remain unchanged.

### Established Patterns
- HTMX fragments update localized regions such as the task card zone, add-task slot, and kanban board.
- SQLC query files are the source for generated DB access; generated Go files are not committed and are reproduced with `just generate`.
- Task reorder currently posts all task IDs and statuses from visible sortable columns, then preserves task title and description by reading each task before update.
- Non-owner access to tablo-scoped resources returns 404 through shared ownership helpers.

### Integration Points
- Add a new etapes migration after `0004_tasks.sql`, with an `etapes` table keyed by tablo and a nullable task etape reference.
- Extend task list queries or add etape-aware list queries so the Tasks tab can render all tasks or one etape filter without changing the status columns.
- Add etape routes under `/tablos/{id}/...`, consistent with existing task and file route patterns.
- Extend task create/update handlers and tests to persist optional etape assignment.
- Extend task reorder tests to prove status-scoped ordering still works when tasks have etapes and when an etape filter is active.

</code_context>

<specifics>
## Specific Ideas

- The first functional UI is a top strip of chips above the kanban.
- Etape chips show task counts.
- Include an `Unassigned` chip.
- Filtering by etape should leave the kanban status columns visually and behaviorally familiar.

</specifics>

<deferred>
## Deferred Ideas

- Etape progress rollups remain deferred.
- Etape templates remain deferred.
- Etape dependencies remain deferred.
- Quick etape assignment from task cards is deferred unless the planner finds it trivial after the form selector is complete.

</deferred>

---

*Phase: 9-Etapes*
*Context gathered: 2026-05-15*
