docs(16): capture phase context

.planning/phases/16-tablo-detail/16-CONTEXT.md

@@ -0,0 +1,145 @@
+# Phase 16: Tablo Detail - Context
+
+**Gathered:** 2026-05-16
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Restyle the tablo detail view — header, task kanban, etapes, and files — using design system components and go-backend CSS patterns. Phase 16 delivers:
+- Tablo detail header restyled: `project-card-top` layout with tablo color avatar, title (inline-editable), and action controls (Discussion, Invite, Delete)
+- Metadata row (Created date, Status pill, Progress bar) kept and restyled with design tokens
+- Description zone moved into the Overview tab (no longer in the persistent header area)
+- Task kanban: horizontal 3-column layout (Todo / In Progress / Done) with `tasks-section-header` column headers and `tasks-section` row-style task cards
+- Etape grouping: tasks grouped under etape headings inside each kanban column; unassigned tasks at bottom; always expanded; EtapeStrip removed
+- Files section: `overview-section-heading` header with upload form on the right + table component with Download + Delete per file row + empty state
+- All existing task, etape, and file handler tests pass unchanged
+
+Does NOT include: chat/planning restyling (Phase 17), mobile-responsive layout, sidebar collapse, new routes or data models.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Tablo Detail Header
+- **D-H01:** Header uses `.project-card-top` layout (from `app.css`, same as dashboard project cards): tablo color circle avatar (left) + title zone (inline-editable, same `tablo-title-zone` pattern) + action controls (right). Port `.project-card-top` CSS if not already available from Phase 15.
+- **D-H02:** Action controls in the header: Discussion link button, Invite button, Delete icon button — all three kept, restyled with `ui.Button` / `ui.IconButton`. Hardcoded colors (`#804EEC`) replaced with design token equivalents.
+- **D-H03:** Tablo color avatar: same colored circle pattern as `sidebar-project-icon` (Phase 15). Uses `tablo.Color` field; falls back to neutral token color when null/empty.
+- **D-H04:** Metadata row (Created date, Status pill, Progress bar) is kept — restyled using design tokens (`var(--...)`) instead of hardcoded hex values. Status pill uses `@ui.Badge(...)`. No behavior change.
+- **D-H05:** Description zone moves from the persistent header area (above tabs) into the Overview tab content. `TabloOverviewTabFragment` renders both the description display/edit zone and whatever overview content exists.
+- **D-H06:** Tab nav bar: replace hardcoded color classes with design token CSS classes. Preserve all existing tabs (Overview, Tasks, Files, Discussion, Events) and their HTMX behavior unchanged.
+
+### Kanban (Tasks Tab)
+- **D-K01:** Kanban layout stays horizontal — 3 columns side by side (Todo / In Progress / Done). Drag-and-drop reorder between columns preserved (Sortable.js wiring unchanged).
+- **D-K02:** Column headers use `.tasks-section-header` CSS (from go-backend `app.css`): status label + task count badge (e.g., "Todo · 3") + Add task button on the right. Port `.tasks-section-header` CSS into `backend/internal/web/ui/app.css` (or existing `app.css`).
+- **D-K03:** Task cards within each column use a row style matching `.tasks-section` layout: checkbox + task title + meta (etape label, priority) inline. Replace the current `.task-card` raw styling with `.tasks-section` CSS. Port `.tasks-section` and related CSS from go-backend `app.css`.
+- **D-K04:** The existing `KanbanBoard`, `KanbanColumn`, `TaskCard` templ components are restyled in-place — no structural change to HTMX endpoints or handler signatures.
+
+### Etape Grouping
+- **D-E01:** `EtapeStrip` (horizontal filter pills) is removed from the tasks tab. Tasks are now grouped by etape inside each kanban column.
+- **D-E02:** Within each kanban column, tasks are rendered in etape groups: a sub-heading per etape (etape name/color) followed by that etape's tasks. Tasks not assigned to any etape appear at the bottom of the column under an "Unassigned" or empty-label group.
+- **D-E03:** Etape group headings are always expanded — no collapse toggle. No JS interaction needed for grouping state.
+- **D-E04:** The grouping is computed server-side in `KanbanColumn` (Go-level grouping logic): for each column's task list, group by etape ID, render each etape's tasks in sequence, then unassigned tasks at the end.
+- **D-E05:** `EtapeFilter` type and the filter HTMX logic may be retained in the codebase (for handler compatibility) but the UI strip that drove it is removed. Handlers continue to accept the filter param but the UI no longer generates it — effectively the filter defaults to "all" permanently.
+
+### Files Section
+- **D-F01:** Files section header uses `.overview-section-heading` pattern (matching go-backend): "Files" label on the left + upload button/trigger on the right.
+- **D-F02:** File list uses `@ui.Table(...)` component (Phase 13). Columns: filename, size, upload date, actions (Download + Delete).
+- **D-F03:** Each file row has two icon buttons: Download (`@ui.IconButton` with download icon, links to file URL) and Delete (`@ui.IconButton` with trash icon, HTMX delete flow with confirm fragment — existing `FileDeleteConfirmFragment` preserved).
+- **D-F04:** Empty state uses `@ui.EmptyState(ui.EmptyStateProps{Title: "No files yet", Description: "Upload your first file to get started."})` — replaces existing `FileListEmpty()`.
+
+### Claude's Discretion
+- Exact sub-heading style for etape groups inside kanban columns (a styled `<div>` or small `<h4>` with the etape color indicator + name; match go-backend task group patterns if any exist)
+- Whether `EtapeFilter` param is fully removed from all handlers or just hidden from UI (recommend keeping the type for handler compatibility, defaulting to "show all")
+- Exact badge token for the "In progress" status pill in the metadata row (use `BadgeVariantPrimary` or `BadgeVariantNeutral` per design token alignment)
+- Tab nav active state CSS — whether to use a CSS class (`is-active`) or inline conditional classes (match Phase 15 `AppLayout` nav item pattern for consistency)
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Product Scope
+- `.planning/ROADMAP.md` — Phase 16 goal, success criteria (5 criteria), requirements DETAIL-01/02/03/04, user-in-loop note
+- `.planning/REQUIREMENTS.md` — DETAIL-01 (header), DETAIL-02 (tasks kanban), DETAIL-03 (etapes), DETAIL-04 (files)
+- `.planning/PROJECT.md` — v3.0 scope: visual polish only, go-backend is the visual reference
+
+### Reference Implementation (source of truth)
+- `go-backend/internal/web/ui/app.css` — CSS patterns to port: `.project-card-top`, `.tasks-section`, `.tasks-section-header`, `.overview-section`, `.overview-section-heading`, `.tasks-section-header h3` — extract these sections only
+- `go-backend/internal/web/views/tasks.templ` — `TasksKanbanLayout`, `TasksListLayout`, `TaskCard`, `TasksListRow` — task card/row visual structure to adapt
+- `go-backend/internal/web/views/dashboard_components.templ` — `DashboardPage`, `SidebarProjectsSection` — color avatar pattern (`.sidebar-project-icon`) already used in Phase 15
+
+### Current Backend (files being changed)
+- `backend/templates/tablos.templ` — `TabloDetailPage`, `TabloOverviewTabFragment`, `TabloTitleDisplay`, `TabloTitleEditFragment`, `TabloDescDisplay`, `TabloDescEditFragment`, `TabloDeleteButtonFragment`, `TabloDeleteConfirmFragment` — header + overview tab restyling
+- `backend/templates/tasks.templ` — `KanbanBoard`, `KanbanColumn`, `TaskCard`, `AddTaskTrigger`, `TaskCardOOB`, `TaskCardGone` — kanban restyling + etape grouping
+- `backend/templates/etapes.templ` — `EtapeStrip` is removed; `EtapeEditFormFragment`, `EtapeCreateFormFragment`, `EtapeDeleteConfirmFragment` are preserved
+- `backend/templates/files.templ` — `FilesTabFragment`, `FileListRow`, `FileListEmpty` — files section restyling
+- `backend/internal/web/ui/app.css` — receives ported CSS sections from go-backend
+
+### Design System (Phase 13 — already in backend)
+- `backend/internal/web/ui/base.css` — design tokens; ALL new CSS must use `var(--...)` tokens, no hardcoded hex values
+- `backend/internal/web/ui/badge.templ` — `@ui.Badge(...)` for status pill and etape count badge
+- `backend/internal/web/ui/icon_button.templ` — `@ui.IconButton(...)` for action controls and file row actions
+- `backend/internal/web/ui/button.templ` — `@ui.Button(...)` for primary action buttons
+- `backend/internal/web/ui/table.templ` — `@ui.Table(...)` for files list
+- `backend/internal/web/ui/empty_state.templ` — `@ui.EmptyState(...)` for file empty state
+
+### Phase 15 Context (patterns established)
+- `.planning/phases/15-dashboard-tablos/15-CONTEXT.md` — `AppLayout` signature, color avatar implementation (`tablo.Color`), `.project-card-top` CSS already ported
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `@ui.Badge(...)` (Phase 13): Use for status pill ("In progress"), etape count, and task count in column headers
+- `@ui.IconButton(...)` (Phase 13): Use for Discussion, Delete in header and Download, Delete in file rows
+- `@ui.Button(...)` (Phase 13): Use for Invite button and file upload trigger
+- `@ui.Table(...)` (Phase 13): Ready for files list — replace the current raw `<table>` in `FilesTabFragment`
+- `@ui.EmptyState(...)` (Phase 13): Replace `FileListEmpty()` templ
+- `AppLayout` (Phase 15): Already wraps `TabloDetailPage` — no change needed
+- `.project-card-top` CSS (Phase 15): Already ported to `app.css` for dashboard cards — reuse for the header zone
+
+### Established Patterns
+- `tablo-title-zone` inline edit pattern: `TabloTitleDisplay` + `TabloTitleEditFragment` — preserve exactly, just wrap in project-card-top layout
+- `tablo-desc-zone` inline edit pattern: `TabloDescDisplay` + `TabloDescEditFragment` — preserve exactly, move to Overview tab
+- `tablo-delete-zone` + `TabloDeleteButtonFragment` + `TabloDeleteConfirmFragment` — preserve exactly, restyle with `ui.IconButton`
+- HTMX tab switching via `hx-target="#tab-content"` — preserve all tab routing logic
+- Sortable.js drag-and-drop in `KanbanBoard` — preserve JS initialization intact
+
+### Integration Points
+- `backend/templates/tablos.templ` `TabloDetailPage`: accepts `etapes []sqlc.Etape` — grouping logic added to `KanbanColumn` using this slice
+- `backend/internal/web/handlers_tablos.go` (or equivalent): handler passes `EtapeFilter` to `KanbanBoard` — filter default stays "all" after EtapeStrip removal; no handler signature change needed
+- `backend/internal/web/ui/app.css`: receives `.tasks-section`, `.tasks-section-header`, `.overview-section-heading` CSS from go-backend — appended to existing file
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- Task grouping inside kanban column: each etape group renders as a small `<div class="etape-group">` with a header row (etape color dot + etape name) followed by task rows. Unassigned group uses a plain "–" or "No etape" label. No collapse toggle.
+- EtapeStrip is fully removed from `TasksTabFragment` — the `@EtapeStrip(...)` call in `TasksTabFragment` is deleted, and the `EtapeFilter` that it generated defaults to "all etapes" at the handler level.
+- Files upload form position: sits in the `.overview-section-heading` header (`<div class="overview-section-heading"><h3>Files</h3><button>Upload</button></div>`). The inline `FileUploadForm` is triggered from this button, not from a standalone form block.
+- Status pill in metadata row: `@ui.Badge(ui.BadgeProps{Label: "In progress", Variant: ui.BadgeVariantPrimary})` or equivalent — Claude's call on the exact variant.
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Collapse toggle for etape groups — could be added in a future polish phase with a small JS interaction
+- Mobile-responsive kanban (horizontal columns are hard on narrow screens) — deferred; Future requirement RESP-01
+- Etape management UI from within the tablo detail (reorder, rename, color etapes) — out of scope for Phase 16
+- Task priority/assignee display in task rows — out of scope; would require new data model fields
+- Files: preview pane or thumbnail generation — deferred; requires file type detection + S3 presigned URL work
+
+</deferred>
+
+---
+
+*Phase: 16-tablo-detail*
+*Context gathered: 2026-05-16*

.planning/phases/16-tablo-detail/16-DISCUSSION-LOG.md

@@ -0,0 +1,152 @@
+# Phase 16: Tablo Detail - 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-16
+**Phase:** 16-tablo-detail
+**Areas discussed:** Header layout, Kanban shape, Etape grouping, Files section
+
+---
+
+## Header layout
+
+### Metadata row
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Drop it entirely | Remove — fake data, visual noise | |
+| Keep it, restyle with tokens | Port using design tokens; static data acceptable as placeholder | ✓ |
+| Move to Overview tab | Keep Created date, move Status/Progress to Overview tab | |
+
+**User's choice:** Keep it, restyle with tokens
+
+### Avatar
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Yes, tablo color circle | Colored circle from tablo.Color — consistent with sidebar + project cards | ✓ |
+| No avatar — title only | Simpler header without avatar | |
+
+**User's choice:** Yes, tablo color circle
+
+### Description zone position
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Stay below header, above tabs | Keep current position — always visible | |
+| Move into the Overview tab | Description only shows on Overview tab — cleaner header on Tasks/Files | ✓ |
+
+**User's choice:** Move into the Overview tab
+
+### Action controls
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Discussion + Delete only | Drop Invite (placeholder, no handler) | |
+| All three, restyled | Keep Discussion, Invite, Delete — all restyled with ui.Button/ui.IconButton | ✓ |
+| Delete only in header | Discussion reachable via tab nav | |
+
+**User's choice:** All three, restyled
+
+---
+
+## Kanban shape
+
+### Layout
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Keep horizontal columns | Todo / In Progress / Done side-by-side; drag-and-drop preserved | ✓ |
+| Fold to vertical list | Single column grouped by status | |
+
+**User's choice:** Keep horizontal columns
+
+### Task card design
+| Option | Description | Selected |
+|--------|-------------|----------|
+| tasks-section row style | Checkbox + title + meta inline; matches go-backend TasksListRow | ✓ |
+| Mini card with shadow | White card per task; classic kanban look | |
+| You decide | Default to tasks-section row style | |
+
+**User's choice:** tasks-section row style
+
+### Column header style
+| Option | Description | Selected |
+|--------|-------------|----------|
+| tasks-section-header style | Status label + task count badge + Add button | ✓ |
+| Simple bold text | Just a bold label | |
+
+**User's choice:** tasks-section-header style with count badge
+
+---
+
+## Etape grouping
+
+### Etape UI approach
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Keep as filter strip | EtapeStrip as horizontal pill filters above kanban | |
+| Group tasks under etape headings | Tasks grouped by etape inside each kanban column | ✓ |
+| You decide | Default to filter strip | |
+
+**User's choice:** Group tasks under etape headings inside kanban columns
+
+### Unassigned tasks
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Ungrouped at bottom | Below all etape groups, plain "Unassigned" label | ✓ |
+| Hidden | Only etape-assigned tasks shown | |
+| Shown first, ungrouped | At top of each column before etape groups | |
+
+**User's choice:** Ungrouped at bottom
+
+### Collapsibility
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Always expanded, not collapsible | No JS needed for collapse | ✓ |
+| Collapsible with toggle | Click to hide/show tasks per group | |
+
+**User's choice:** Always expanded, not collapsible
+
+### EtapeStrip fate
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Remove it entirely | Replaced by inline grouping | ✓ |
+| Keep as grouped/flat toggle | Simplified version to switch between grouped and flat view | |
+
+**User's choice:** Remove it entirely
+
+---
+
+## Files section
+
+### Row actions
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Download + Delete | Two icon buttons per row | ✓ |
+| Download only (delete via menu) | Cleaner rows, overflow menu | |
+| You decide | Default to Download + Delete | |
+
+**User's choice:** Download + Delete
+
+### Upload form position
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Above the table, in section header | overview-section-heading pattern — heading + upload button on right | ✓ |
+| Below the table | Table first, upload form at bottom | |
+| You decide | Default to above table | |
+
+**User's choice:** Above the table, in a section header
+
+---
+
+## Claude's Discretion
+
+- Exact sub-heading style for etape groups inside kanban columns
+- Whether `EtapeFilter` param is fully removed from handlers or kept as "all" default
+- Exact badge variant for the "In progress" status pill in the metadata row
+- Tab nav active state CSS (CSS class vs. inline conditional)
+
+## Deferred Ideas
+
+- Collapse toggle for etape groups — future polish phase
+- Mobile-responsive kanban — Future requirement RESP-01
+- Etape management UI from within tablo detail — future phase
+- Task priority/assignee in task rows — requires new data model
+- Files: preview pane or thumbnail generation — requires file type + presigned URL work