fix(timeline): EPIC-06 UAT fixes — projected dates, late milestones, work item scheduling UX

[steilerDev]

Summary

Addresses 5 UAT feedback items identified during EPIC-06 manual validation:

• Fix 1: Remove milestone filter dropdown from timeline toolbar (UX simplification)
• Fix 2: Add projectedDate to TimelineMilestone — computed as max endDate of linked work items; display in Gantt tooltip; render late milestones in red
• Fix 3: Support workItemIds on milestone creation — build WorkItemSelector chip component and integrate into MilestoneForm
• Fix 4: Replace portal-based MilestoneWorkItemLinker with in-form WorkItemSelector
• Fix 5: Show startDate/endDate as read-only computed fields on WorkItemDetailPage; show durationDays, startAfter, startBefore as editable inputs on both create and detail pages

Changes

Backend (server/, shared/)

• shared/src/types/milestone.ts: Added workItemIds?: string[] to CreateMilestoneRequest
• shared/src/types/timeline.ts: Added projectedDate: string | null to TimelineMilestone
• server/src/services/timelineService.ts: Compute projectedDate from max endDate of linked work items
• server/src/services/milestoneService.ts: Accept and link workItemIds on creation
• server/src/routes/milestones.ts: Pass workItemIds through from request body

Frontend (client/)

• WorkItemSelector component: new chip-based multi-select with debounced search dropdown
• MilestoneForm.tsx: Integrated WorkItemSelector; removed portal dependency
• MilestonePanel.tsx: Pass projectedDates map; added projected date display
• GanttMilestones.tsx: Export computeMilestoneStatus(); render late diamonds in red
• GanttTooltip.tsx: Show projected date in tooltip
• WorkItemDetailPage.tsx: startDate/endDate read-only; durationDays/startAfter/startBefore editable
• WorkItemCreatePage.tsx: Show scheduling constraint fields (durationDays, startAfter, startBefore) on create form
• TimelinePage.tsx: Removed milestone filter dropdown

Test Coverage

File	New Tests	Description
server/src/services/timelineService.test.ts	+6	projectedDate computation scenarios
server/src/services/milestoneService.test.ts	+5	workItemIds on creation
server/src/routes/milestones.test.ts	+4	workItemIds integration tests
server/src/routes/timeline.test.ts	+4	projectedDate in API response
client/src/components/GanttChart/GanttMilestones.test.tsx	+10	computeMilestoneStatus() + late colors
client/src/components/milestones/WorkItemSelector.test.tsx	+27 (new file)	Full component coverage
client/src/components/milestones/MilestoneForm.test.tsx	+7	workItemIds field
client/src/components/milestones/MilestonePanel.test.tsx	+6	projectedDates prop
client/src/pages/WorkItemDetailPage/WorkItemDetailPage.test.tsx	+10	Schedule + Constraints sections
client/src/pages/WorkItemCreatePage/WorkItemCreatePage.test.tsx	+4	Constraint inputs on create
client/src/components/calendar/*.test.*	+1 each	projectedDate: null fixture updates

Test Plan

• CI quality gates pass (lint, typecheck, build, unit/integration tests)
• E2E smoke tests pass in CI
• All server integration tests pass (timelineService, milestoneService, routes)
• All client unit tests pass (GanttMilestones, WorkItemSelector, MilestoneForm, MilestonePanel, WorkItemDetailPage, WorkItemCreatePage)
• Manual UAT validation: projected date shows in Gantt tooltip for milestones with linked work items
• Manual UAT validation: late milestones render in red diamond
• Manual UAT validation: work items can be linked to milestones at creation time via WorkItemSelector

Fixes #6

🤖 Generated with Claude Code

Co-Authored-By: Claude qa-integration-tester (Sonnet 4.6) noreply@anthropic.com

[steilerDev]

[product-owner] PR Review: APPROVED

I have completed a systematic review of all 6 UAT feedback items against the implementation in this PR.

Requirements Coverage -- All 6 UAT Fixes Addressed

UAT Feedback Item	PR Fix	Verified
1. Duplicate Milestones buttons	Fix 1: MilestoneFilterDropdown and all related CSS removed from TimelinePage; only the panel toggle button remains	PASS
2. Milestones need projected date	Fix 2: projectedDate added to TimelineMilestone in shared types; computed in timelineService as max endDate of linked work items; displayed in GanttTooltip and MilestonePanel	PASS
3. Cannot link work items during creation	Fix 3: workItemIds added to CreateMilestoneRequest; WorkItemSelector integrated into MilestoneForm (create mode only); backend accepts and links atomically	PASS
4. Selector dropdown clipped by overflow	Fix 4: New WorkItemSelector uses createPortal with position fixed and z-index 1100; replaces inline dropdown in MilestoneForm and MilestoneWorkItemLinker	PASS
5. Work item schedule fields UX	Fix 5: startDate and endDate converted to read-only spans on detail page; removed from create page; durationDays moved into Constraints section	PASS
6. Milestone late visual state	Fix 2 combined: computeMilestoneStatus returns completed, late, or on_track; late diamonds use danger color tokens in both light and dark themes	PASS

Acceptance Criteria Alignment

• Projected date computation: max endDate of linked work items, null when no items have dates
• Late status precedence: completed > late > on_track (completed milestones never show late)
• Design tokens for light and dark themes in tokens.css
• WorkItemSelector edge cases: empty selection, invalid IDs silently skipped, backward compatibility
• WorkItemSelector in create mode only (edit uses existing linker dialog)
• Help text explains projected date concept to homeowners

Agent Responsibilities

• QA: 88 new tests across 11 files. WorkItemSelector has 27 tests. Full coverage of computeMilestoneStatus, projected date computation, work item linking, read-only fields, and constraints.
• Security: Not yet reviewed on this PR. Low risk (no new auth flows, no new endpoints -- just extending existing payloads) but still needed per process.
• Visual: Substantial frontend changes (new component, token additions, UX restructuring). UX designer review recommended for token adherence and accessibility.

Scope Discipline

All changes map directly to the 6 UAT feedback items. No scope creep. The MilestoneWorkItemLinker refactor to reuse WorkItemSelector is an appropriate DRY improvement.

Note

PR body says "5 UAT feedback items" but actually covers all 6 (items 2 and 6 from the UAT feedback are bundled into Fix 2). CI is fully green: Quality Gates, Docker, E2E Smoke Tests all pass.

[steilerDev]

[security-engineer] PR #263 Security Review — EPIC-06 UAT Fixes

Reviewed PR diff, key source files, and the Security Audit wiki page history. Five focus areas assessed below.

---

1. Input Validation — workItemIds Array

Route schema (server/src/routes/milestones.ts):

workItemIds: {
  type: 'array',
  items: { type: 'string' },
},

The schema validates that workItemIds is an array of strings. additionalProperties: false is already present on the body schema — this is correct. The field is optional (not in required), which is the right design choice for backward compatibility.

One gap identified: The items schema does not constrain string length (e.g., no maxLength). A caller could submit an array containing extremely long strings (e.g., a 10 MB UUID-shaped string) or a very large array. Neither would be exploitable for injection (Drizzle parameterizes all queries), but they represent a minor DoS vector. Adding maxLength: 36 (UUID length) and maxItems: 200 would align with the project's defense-in-depth pattern documented in the existing finding "Missing server-side maxLength on text fields".

Service layer (server/src/services/milestoneService.ts, lines 202-210):

for (const workItemId of data.workItemIds) {
  const workItem = db.select().from(workItems).where(eq(workItems.id, workItemId)).get();
  if (workItem) {
    db.insert(milestoneWorkItems).values({ milestoneId: result.id, workItemId }).run();
  }
}

The existence check before the insert is correct — non-existent IDs are silently skipped, avoiding both foreign key errors and information disclosure about valid IDs. All DB operations use Drizzle ORM parameterized queries (eq() with where); no raw SQL injection risk.

The loop runs N+1 queries (one SELECT per ID, then one INSERT per valid ID). For reasonable array sizes this is fine. The implicit maxItems gap is the only concern.

Assessment: No injection risk. One informational observation — see findings below.

---

2. Portal Rendering — WorkItemSelector XSS

client/src/components/milestones/WorkItemSelector.tsx

The component uses createPortal to render to document.body. I checked all text rendering paths:

• Chip labels (line 215): {item.name.length > 30 ? \${item.name.slice(0, 30)}\u2026` : item.name}— React JSX text interpolation; auto-escaped. NodangerouslySetInnerHTML`.
• Dropdown item titles (line 305): {item.title} — React JSX text interpolation; auto-escaped.
• Dropdown item status (line 306): {item.status} — enum value sourced from API; auto-escaped.
• Error message (line 278): {searchError} — sourced from a hardcoded string 'Failed to load work items'; no user input reflected.
• title attribute (line 214): title={item.name} — React sets this as a DOM attribute through setAttribute, not via HTML injection.
• aria-label (line 222): \Remove ${item.name}`` — rendered as a DOM attribute value; no injection vector.

No dangerouslySetInnerHTML, innerHTML, eval(), or document.write() usage anywhere in the component. The createPortal call is safe — it renders a React virtual DOM tree to document.body, and all dynamic content remains in React's controlled rendering pipeline.

The outside-click handler uses document.querySelector('[data-work-item-selector-dropdown]') to identify portal content. This is a legitimate pattern and carries no security risk.

Assessment: No XSS risk. Portal usage is clean.

---

3. SQL/ORM Safety

All new DB operations in this PR use Drizzle ORM query builders exclusively:

• milestoneService.ts: db.select().from(workItems).where(eq(workItems.id, workItemId)).get() — parameterized
• milestoneService.ts: db.insert(milestoneWorkItems).values({...}).run() — parameterized
• timelineService.ts: All operations use pre-existing Drizzle query patterns; the new projectedDate computation is pure in-memory JavaScript (no additional DB queries) iterating over already-fetched data

No raw SQL strings, template literals with user input, or db.run() with unparameterized input anywhere in the diff.

Assessment: No SQL injection risk.

---

4. Authorization

All new and modified endpoints continue to use the existing if (!request.user) { throw new UnauthorizedError(); } guard pattern. The new workItemIds field flows through the existing POST /api/milestones handler, which already required authentication. No new unauthenticated routes are introduced.

The projectedDate computation in getTimeline() runs on already-fetched, auth-gated data — no new DB queries are introduced that bypass the session check on the route handler.

Assessment: Authorization is correctly maintained.

---

5. projectedDate Data Exposure

The projectedDate field is computed as the max endDate of linked work items. Review:

• endDate values are non-sensitive scheduling data (already included in the TimelineWorkItem objects returned by the same endpoint)
• The computation reveals no new data classes — it is a derived value from data the client already receives
• No user PII, credentials, financial amounts, or internal system details are included
• The projectedDate: null case is handled correctly (no undefined leakage)

Assessment: No sensitive data exposure.

---

Findings

[INFORMATIONAL] workItemIds Schema Lacks maxItems and String maxLength Constraints

OWASP Category: A05 — Security Misconfiguration (defense-in-depth gap)
Severity: Informational (does not block merge)

The workItemIds array in createMilestoneSchema has no maxItems bound and no maxLength on individual string items. A caller can submit an arbitrarily large array or arbitrarily long strings. The service-layer loop processes each ID with a DB round-trip, creating a DoS vector proportional to array length. This is consistent with the existing pattern of open findings for missing length bounds (see Security Audit page).

Affected file: server/src/routes/milestones.ts — workItemIds schema definition

Remediation (can be addressed in a future hardening pass alongside the existing open findings):

workItemIds: {
  type: 'array',
  items: { type: 'string', maxLength: 36 },
  maxItems: 200,
},

---

Checklist

• No SQL/command/XSS injection vectors in new code
• Authentication/authorization enforced on all new endpoints
• No sensitive data (secrets, tokens, PII) exposed in logs, errors, or client responses
• User input validated and sanitized at API boundaries (Drizzle ORM + Fastify schema validation)
• No new dependencies introduced
• No hardcoded credentials or secrets
• CORS configuration unchanged
• Error responses do not leak internal details

---

Result: APPROVED. The new workItemIds feature, projectedDate computation, portal dropdown, and frontend rendering all pass security review. One informational finding (schema bounds on workItemIds) is logged on the Security Audit wiki page and does not block merge.

[steilerDev]

[ux-designer] Visual/UX review of PR #263 — EPIC-06 UAT fixes. APPROVED (posted as comment due to GitHub self-review restriction).

Design Token Adherence

Late milestone tokens — properly defined in tokens.css Layer 2 with semantic names:

• --color-milestone-late-fill: var(--color-danger) and --color-milestone-late-stroke: var(--color-danger-hover) in :root
• --color-milestone-late-hover-glow: rgba(220, 38, 38, 0.25) in :root, rgba(239, 68, 68, 0.3) in dark
• GanttChart.tsx resolves these via readCssVar() with sensible fallbacks (|| readCssVar('--color-danger'))
• MilestonePanel.module.css uses var(--color-milestone-late-fill, var(--color-danger)) with fallback — correct

WorkItemSelector.module.css — all 167 lines reference design tokens correctly:

• Borders: var(--color-border-strong), var(--color-border-focus)
• Backgrounds: var(--color-bg-primary), var(--color-primary-bg), var(--color-bg-tertiary)
• Text: var(--color-text-primary), var(--color-text-placeholder), var(--color-text-secondary), var(--color-text-muted), var(--color-primary-badge-text)
• Spacing, radius, shadows, transitions all use token vars — no hardcoded colors found

MilestonePanel.module.css additions — new classes use tokens:

• .milestoneItemProjected: var(--font-size-xs), var(--color-text-muted)
• .milestoneItemProjectedLate: var(--color-danger-text-on-light), var(--font-weight-medium)
• .fieldHint: var(--font-size-xs), var(--color-text-muted), var(--spacing-1-5)

WorkItemDetailPage.module.css — .propertyValue and .sectionDescription use hardcoded rem values rather than var(--font-size-sm) / var(--font-size-2xs) tokens. However, this matches the pre-existing pattern in the file (all 20+ existing rules use hardcoded rem). Consistent with existing file conventions — acceptable.

Dark Mode Support

• tokens.css dark overrides present for all three new milestone-late tokens (--color-milestone-late-fill, --color-milestone-late-stroke, --color-milestone-late-hover-glow) — uses var(--color-danger) which resolves to --color-red-400 in dark mode. Correct.
• GanttTooltip.module.css has [data-theme='dark'] .detailValueLate { color: var(--color-red-400); } — correct override from the light mode var(--color-red-200).
• WorkItemSelector.module.css has no explicit dark overrides, but every property references semantic tokens that already have dark overrides in tokens.css (e.g., --color-bg-primary, --color-border-strong, --color-text-primary). The portal dropdown will inherit correct dark mode colors automatically. Correct approach.
• MilestonePanel.module.css — existing file has no dark overrides (uses semantic tokens throughout). The new additions (.diamondLate, .milestoneItemProjected, .milestoneItemProjectedLate, .fieldHint) follow the same pattern — --color-danger-text-on-light resolves to --color-red-300 in dark mode. Correct.

Accessibility

• Late milestone state conveyed beyond color: The aria-label on late diamond markers includes the word "late" (Milestone: ${title}, late, target date ${targetDate}). The tooltip shows "Late" status badge. Test confirms: expect(label.toLowerCase()).toContain('late'). Good.
• WorkItemSelector keyboard navigation: Escape closes dropdown (both from input keydown handler and document-level keydown listener). Backspace on empty input removes last chip. Input has aria-haspopup="listbox", aria-expanded, aria-controls. Dropdown list has role="listbox", items have role="option", tabIndex={0}, onKeyDown for Enter/Space. Remove buttons have descriptive aria-label. Comprehensive.
• Read-only schedule fields: Changed from <label> + <input type="date"> to <span> + <span>. Since these are display-only (not editable), this is semantically correct — they are informational text, not form controls. The explanatory text "computed by the scheduling engine" is rendered as a visible <p> which provides context.
• MilestonePanel status labels: The aria-label on milestone buttons includes the status: ${m.title}, ${statusLabel}, ${formatDate(m.targetDate)} where statusLabel is "completed", "late", or "incomplete". Accessible.

Responsive Behavior

The removed milestone filter dropdown CSS (196 lines) is cleanly excised — both the main styles and the @media responsive overrides (.milestoneFilterButton { min-height: 44px } and .milestoneFilterLabel { display: none }) are removed together. The DiamondIcon helper component was also removed and replaced with an inline SVG in the one remaining usage (milestones panel toggle button). No orphaned responsive breakpoint CSS detected.

Visual Consistency

• WorkItemSelector chips: Follow the same chip pattern as MilestoneWorkItemLinker (same pill shape --radius-full, same blue background --color-primary-bg, same truncation at 30 chars, same X button with SVG cross icon). The component correctly extracts this into a reusable form with portal-based dropdown.
• Help text: .fieldHint uses --font-size-xs + --color-text-muted + line-height: 1.5 — matches the existing help text pattern in form components.
• Projected date in milestone list: Uses --font-size-xs with --color-text-muted for normal state and --color-danger-text-on-light + --font-weight-medium for late state — consistent with how other "danger" indicators are styled across the app.

Result: APPROVED. Token usage, dark mode, accessibility, and visual patterns all look solid.

[steilerDev]

[security-engineer] Security review complete — no blocking issues found. Approving on behalf of the security-engineer role. One informational finding (workItemIds schema lacks maxItems/maxLength bounds) has been logged on the Security Audit wiki page and does not block merge.

[steilerDev]

[product-architect] Architectural review of PR #263 — EPIC-06 UAT fixes.

Verdict: APPROVED

I have reviewed the full diff (38 files, +2180/-904) against the established architecture, API contract, schema, and coding conventions.

Architecture Compliance

Patterns followed correctly:

• Fastify routes: The createMilestoneSchema JSON schema properly extends with workItemIds as an optional array of strings. Schema validation is consistent with all other endpoints.
• Drizzle ORM: The milestoneService.createMilestone uses standard Drizzle select().from().where().get() and insert().values().run() patterns. Work item existence validation before linking is a sound defensive approach.
• CSS Modules: The new WorkItemSelector.module.css follows the established component-scoped module pattern. All new CSS classes use design tokens from tokens.css (e.g., var(--color-border-strong), var(--spacing-2), var(--color-primary-bg)).
• React hooks/components: WorkItemSelector follows the established component patterns — useState/useRef/useCallback/useEffect hooks, memo where appropriate, proper cleanup in effects.
• Design tokens: New milestone late tokens (--color-milestone-late-fill, --color-milestone-late-stroke, --color-milestone-late-hover-glow) are properly added to both light and dark mode sections of tokens.css.

Code Quality

• TypeScript: No unjustified any types. The one eslint-disable for @typescript-eslint/no-explicit-any in MilestonePanel.test.tsx (line 741) is pre-existing and appropriately scoped.
• ESM imports: All .js extensions present on import paths.
• Type imports: import type used correctly throughout (e.g., import type { WorkItemSummary } from '@cornerstone/shared').
• Exported types: MilestoneStatus, SelectedWorkItem, computeMilestoneStatus are cleanly exported for reuse.
• String comparison for date ordering: The projectedDate > milestone.targetDate comparison works correctly for ISO 8601 date strings (YYYY-MM-DD format is lexicographically orderable).

API Contract & Schema Consistency

• CreateMilestoneRequest.workItemIds?: string[]: Optional array, backward compatible. Existing clients sending no workItemIds field will continue to work. The Fastify JSON schema mirrors the TypeScript interface.
• TimelineMilestone.projectedDate: string | null: Additive, non-breaking field. Computed server-side from MAX(work_items.end_date) of linked items. The computation in timelineService.ts is efficient — it builds an endDateMap from already-fetched work items rather than issuing additional queries.
• Note: The Wiki API Contract page does not yet document EPIC-06 milestone/timeline endpoints. This is a pre-existing gap (the wiki was never updated for EPIC-06), not introduced by this PR.

Test Coverage

83 new tests across 11 files provide thorough coverage:

• computeMilestoneStatus — 7 unit tests covering all status branches (completed, late, on_track) including edge cases
• WorkItemSelector — 27 new tests (full component coverage for the new reusable component)
• timelineService — 6 tests for projectedDate computation (max endDate, null cases, mixed dates)
• milestoneService — 5 tests for workItemIds on creation (valid IDs, empty array, invalid IDs, backward compat)
• Route integration tests — 4 for milestones, 4 for timeline
• Existing test fixtures updated with projectedDate: null across all calendar tests

The test coverage is well-structured and targets the right edge cases.

Observations (non-blocking)

1. WorkItemDetailPage.module.css hardcoded rem values: The new .propertyValue and .sectionDescription classes use hardcoded 0.875rem, 0.8125rem, 0.625rem rather than design tokens (--font-size-sm, --font-size-xs, --spacing-2-5). This matches the pre-existing style of the file (the entire WorkItemDetailPage.module.css uses hardcoded rem values), so this is consistent within the file but remains a tech debt item for a future CSS token migration pass on this page.

2. Silent skip of invalid work item IDs: The milestoneService.createMilestone silently skips non-existent work item IDs. This is documented and tested. A future consideration could be returning a warning in the response body listing skipped IDs, but the current approach is pragmatic for a small-user app.

3. Wiki deviation: The API Contract wiki page does not document milestone or timeline endpoints at all. This predates this PR, but should be addressed as part of EPIC-06 documentation before the epic promotion to main.

[github-actions]

🎉 This PR is included in version 1.10.0-beta.14 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀