From ebc209ebd9d55d1e7f8e00661c8fc05eab5e91dd Mon Sep 17 00:00:00 2001 From: Arthur Belleville Date: Fri, 15 May 2026 22:05:46 +0200 Subject: [PATCH] docs(09): capture phase context --- .planning/phases/09-etapes/09-CONTEXT.md | 114 ++++++++++++++++++ .../phases/09-etapes/09-DISCUSSION-LOG.md | 84 +++++++++++++ 2 files changed, 198 insertions(+) create mode 100644 .planning/phases/09-etapes/09-CONTEXT.md create mode 100644 .planning/phases/09-etapes/09-DISCUSSION-LOG.md diff --git a/.planning/phases/09-etapes/09-CONTEXT.md b/.planning/phases/09-etapes/09-CONTEXT.md new file mode 100644 index 0000000..adf01c0 --- /dev/null +++ b/.planning/phases/09-etapes/09-CONTEXT.md @@ -0,0 +1,114 @@ +# Phase 9: Etapes - Context + +**Gathered:** 2026-05-15 +**Status:** Ready for planning + + +## 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. + + + + +## 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. + + + + +## 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. + + + + +## 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. + + + + +## 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. + + + + +## 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. + + + +--- + +*Phase: 9-Etapes* +*Context gathered: 2026-05-15* diff --git a/.planning/phases/09-etapes/09-DISCUSSION-LOG.md b/.planning/phases/09-etapes/09-DISCUSSION-LOG.md new file mode 100644 index 0000000..eeb04aa --- /dev/null +++ b/.planning/phases/09-etapes/09-DISCUSSION-LOG.md @@ -0,0 +1,84 @@ +# Phase 9: Etapes - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md -- this log preserves the alternatives considered. + +**Date:** 2026-05-15 +**Phase:** 9-Etapes +**Areas discussed:** Etape surface, Task grouping behavior, Ordering model, Assignment workflow + +--- + +## Etape Surface + +| Option | Description | Selected | +|--------|-------------|----------| +| Top strip | Compact etape strip above the existing kanban, with create/edit/reorder controls there. Preserves the current task board. | yes | +| Left sidebar | Makes filtering prominent, but reduces kanban space and needs more responsive layout work. | | +| Separate section | Simpler visually, but etapes feel less integrated with daily task work. | | + +**User's choice:** Top strip +**Notes:** User wants something functional now; a beautiful UI will come later. + +### Top Strip Detail + +| Option | Description | Selected | +|--------|-------------|----------| +| Etape chips plus counts | Each etape appears as a compact chip with task count, plus an `Unassigned` chip. | yes | +| Etape cards | Wider blocks with title, description, count, and actions. | | +| Minimal filter only | Just a dropdown or segmented filter, with management elsewhere. | | + +**User's choice:** Etape chips plus counts +**Notes:** Include an `Unassigned` chip. + +--- + +## Task Grouping Behavior + +| Option | Description | Selected | +|--------|-------------|----------| +| Filter the existing kanban | Selecting an etape shows only tasks in that etape, while columns/status/order stay the same. | yes | +| Group inside each status column | Each kanban column is subdivided by etape. | | +| Etape lanes around kanban | Etapes become the primary layout, with statuses inside each etape. | | + +**User's choice:** Filter the existing kanban +**Notes:** Keep the existing kanban model as the primary task view. + +--- + +## Ordering Model + +| Option | Description | Selected | +|--------|-------------|----------| +| Keep current status-scoped task order | Etapes have their own order, tasks keep the existing `(tablo, status, position)` behavior. | yes | +| Scope task order by etape and status | Each etape gets independent task ordering per status. | | +| Agent decides | Planner may choose the simplest implementation that preserves visible behavior. | | + +**User's choice:** Keep current status-scoped task order +**Notes:** This preserves current drag/drop semantics. + +--- + +## Assignment Workflow + +| Option | Description | Selected | +|--------|-------------|----------| +| Task create/edit form | Add an etape selector to the existing task forms. | yes | +| Quick dropdown on task cards | Faster day to day, but more HTMX/card update work. | | +| Both form and quick dropdown | Most complete, but broader than the first functional pass. | | + +**User's choice:** Task create/edit form +**Notes:** Quick assignment on task cards is deferred. + +--- + +## Agent Discretion + +- Planner may choose exact route names, query names, and HTMX fragment boundaries if the locked product behavior is preserved. + +## Deferred Ideas + +- Etape progress rollups. +- Etape templates. +- Etape dependencies. +- Quick assignment dropdowns on task cards.