backlog.md

Project Backlog

Active Task: Remove Agency Messaging and Online User Count (2026-05-31)

• Remove the Agency-Messaging banner text from the application UI.
• Remove the displayed number of online users from the application UI.
• Remove now-unused state/imports and update tests as needed.
• Verify with npm run format, npm run typecheck, npm run lint, npm run build, and npm run test.

Active Task: Remove Online User Graphic (2026-05-31)

• Remove the three-circle online-user/avatar graphic from the top-right navigation area.
• Ensure removing the graphic does not break the header, tabs, or dark-mode control layout.
• Update tests to verify the online-user graphic is absent.
• Verify with npm run format, npm run typecheck, npm run lint, npm run build, and npm run test.

Active Task: Full-Width Content and Remove Keyboard Shortcuts Panel (2026-05-31)

• Remove the constrained max-width wrapper so the main app content uses the available full width.
• Remove the bottom keyboard shortcut panel/button and any related state or imports that become unused.
• Preserve header, navigation tabs, dark-mode control, and tab content behavior.
• Update tests to verify the shortcut panel is absent and the app still renders correctly.
• Verify with npm run format, npm run typecheck, npm run lint, npm run build, and npm run test.

Active Task: Uniform Three-Panel Workspace Layout (2026-05-31)

• Make Argument Editor, Socratic Prompts, and Discourse Graph panels visually uniform.
• Arrange panels in a 1:1:2 width ratio on wide screens.
• At an intermediate breakpoint, keep Argument Editor and Socratic Prompts on the first row and wrap Discourse Graph to the next row.
• At narrow widths, stack all three panels vertically.
• Update tests for the new layout and verify with npm run format, npm run typecheck, npm run lint, npm run build, and npm run test.

Phase 1: Stability & Foundation (High Priority)

• Remove unused Link interface from types.ts
• Remove unused DiscourseData interface from types.ts
• The API key "ollama" is now configurable via VITE_OPENAI_API_KEY
• Add proper error type handling instead of any in llmService.ts
• Remove unused variables: openaiHost, openaiModel in llmService.ts
• Remove unused import Lightbulb from App.tsx
• Replaced D3 DiscourseGraph with Argdown Visualization
• Fixed vite.config.ts import errors using vite-env.d.ts type augmentation
• Removed unused d3 dependency
• Implemented localStorage persistence
• All TypeScript compilation passes successfully
• Add Argdown syntax validation and sanitization layer
• Use dynamic import() to code-split the application (IdeateTab lazy-loaded)
• Added manualChunks config in vite.config.ts for vendor optimization
• Configured ESLint with flat config
• Added unit tests for all components and services
• Added comments to all TypeScript files

Tailwind CSS Migration (High Priority)

• Update dark variant syntax in src/index.css: @custom-variant dark → @variant dark
• Create tailwind.config.js with semantic color definitions and font family extensions
• Removed unused tailwind.config.cjs; only tailwind.config.js is used by Vite
• Add @config directive in src/index.css to import the config file
• Review and update all Tailwind v4 configuration options
• Verify responsive design across all breakpoints
• Test dark mode implementation after updates

Active Task: Collaborative Graph Mockup (2026-06-01)

• Update CollaborativeGraphPanel to display a mockup Argdown graph when no claims are present.
• Include specific claims and evidence in the mockup.
• Update tests to verify the mockup is displayed.
• Verify with npm run format, npm run typecheck, npm run lint, npm run build, and npm run test.

Phase 2: Feature Expansion (Medium Priority)

• The admin notice area shows hardcoded "12 Online" - should come from state
• TabButton component can be extracted to its own file
• Consider extracting localStorage logic into a custom hook (useLocalStorage)
• Consider using custom hooks for AI interaction logic in IdeateTab.tsx
• The prompts are too long - should be in separate prompt templates or a prompts file
• Add request/response logging with proper formatting in llmService.ts
• Show loading skeleton when graph data arrives (Ref: rendering-usetransition-loading)
• Show reasoning as collapsible sections (Ref: rendering-conditional-render)
• Implement Contributions tab content
• Implement "Collaborative Graph" view (multi-user simulation)
• Add keyboard shortcuts
• Improve grammatical placeholder text
• Make graph responsive for mobile
• [DEP0205] DeprecationWarning: module.register() is deprecated. Use module.registerHooks() instead. (Resolved: External dependency issue, safely ignorable)

Phase 3: Polish & Quality (Low Priority)

• Fix inconsistent indentation in IdeateTab.tsx
• Fix trailing spaces in system prompt strings
• Consider renaming cn to something more descriptive in utils.ts
• Consider using loadEnv if env handling needs to expand
• Add proper type imports from @types/react for UserConfig and UserConfigFn types
• Move vite-env.d.ts or create separate type declaration files for better organization
• Remove the triple-slash reference directive and use proper vite-env.d.ts augmentation
• Add proper CSS for argdown styling in ArgdownRenderer.tsx
• The argdown import might need to be dynamically imported for bundle optimization
• Add proper error boundary around ArgdownRenderer.tsx renderer
• Fix vite.config.ts import errors (loadEnv, defineConfig)
• Remove unused d3 dependency (Ref: bundle-size-optimization)
• Add dark mode toggle
• Enhance graph interactivity (zooming, panning, clicking nodes)
• Accessibility audit
• Include unit tests for UI components and services
• Document new env vars and UI changes in README
• Clean up unused imports & dead code (Ref: bundle-barrel-imports)

Phase 4: Nice-to-Have Features

• Implement importing/exporting discourse graphs
• Implement real-time collaboration features
• Add user authentication for persistence

Phase 5: Future Considerations

• Update src/services/llmService.ts to use a web-server to proxy requests to LLM provider
  • Remove direct OpenAI import
  • Import socket.io-client
  • Connect to server on mount
  • Emit llm_request with the prompt, await llm_response
• Update frontend to use new llmService and wait for completion

Phase 6: Pending Plan Requirements (from Verification Report)

• Implement Revision History and Replay (FE-1.4)
• Implement Reference Display for Prompts (FE-2.4)
• Implement Graph Update Highlights (FE-3.3)
• Implement Cluster and Contention Visualization (FE-4.3)
• Implement Contribution Traceability (FE-4.4)
• Implement Support/Challenge Filters for Collaborative Graph (FE-4.6)

Unit Tests

• App.tsx - Test tab switching, renders correctly
• components/TabButton.tsx - Test active/inactive states, click handler
• components/IdeateTab.tsx - Test AI interaction, loading states, error handling
• components/ArgdownRenderer.tsx - Test argdown rendering
• hooks/useLocalStorage.ts - Test read/write operations
• hooks/useAI.ts - Test ideate/submit functionality
• services/llmService.ts - Test prompt generation (mocked API)
• lib/utils.ts - Test clsxMerge function

End-to-End Testing (Cypress)

• Add Cypress config and install dependencies (already done via package.json)
• Write basic test for TabButton component (render with active true/false)
• Write basic test for IdeateTab component (check AI interaction loading state)
• Add Cypress test for app navigation between tabs
• Run Cypress tests locally with bounded Vite server job and command timeout
• Run Cypress tests on CI
• Add CI workflow step to launch app and run npx cypress run --e2e

Phase 0: Frontend Story Verification

• Verify FE-1 prompt/editor workspace matches acceptance criteria.
• Verify FE-2 Ideate action and Socratic prompts meet criteria.
• Verify FE-3 Personal discourse graph meets criteria.
• Verify FE-4 Submission and collaborative graph meets criteria.
• Verify FE-5 Agency, accessibility, and trust meets criteria.

Decision Points

• Q1: Should autosave for draft be implemented before graph updates? Yes.
• Q2: Do we need lazy loading of IdeateTab for performance? No.
• Q3: How to handle async prompt generation failures? Show error message in UI and allow retry.

Active Verification & Completion Criteria (2026-05-31)

• Re-review every user story in plan.md against current implementation and tests.
• Re-verify previously completed backlog items; reopened or added follow-up tasks for gaps found.
• Add a detailed pending-task list for uncovered acceptance criteria and missing tests.
• Execute pending P0/P1 plan requirements until all acceptance criteria are represented in working UI or documented prototype behavior.
• Ensure unit/component/E2E coverage exists for implemented stories and run npm run format, npm run typecheck, npm run lint, npm run build, and npm run test.

Pending Follow-up Tasks from 2026-05-31 Verification

• Wire prototype LLM and graph flows to real backend endpoints instead of mock/local-only data.
• Add CI workflow step to run full unit tests and Cypress E2E tests with the Vite app launched in CI.
• Add import/export for discourse graphs when graph persistence format is finalized.
• Add authentication-backed participant identity and persistence when backend auth is available.
• Investigate upstream Vite/Rolldown [DEP0205] module.register() deprecation warning when dependency updates are available.