UX: Link tasks back to PRD requirements for traceability

[frankbria]

Problem

TaskCard and TaskDetailModal display task details, but users cannot see which PRD requirement(s) each task implements. There is no visible traceability from task → requirement.

Impact

Users cannot trace tasks back to requirements, making it hard to verify completeness, prioritize by business value, or understand why a task exists.

Recommendation

1. Add requirement_id / requirement_ids field to Task model
2. Display requirement badge on TaskCard (e.g., REQ-042) with glitch type indicator
3. Make badge clickable to jump to /proof#REQ-042
4. Include requirement summary in TaskDetailModal

Acceptance Criteria

• Requirement badge visible on task cards
• Requirement ID and title shown in detail modal
• Badge links to proof/PRD page for that requirement
• Works for tasks linked to multiple requirements
• Badge hidden gracefully if no requirement linked

Affected Components

web-ui/src/components/tasks/TaskCard.tsx, web-ui/src/components/tasks/TaskDetailModal.tsx

[traycerai]

Warning

Something went wrong while processing your request.

Reference ID: 79dcd115-fe61-414d-85f2-9ac91f928672

Please try again or contact support if the issue persists, referencing this ID.

[coderabbitai]

🔗 Related PRs

#49 - feat: Add inline dependency rendering to TaskTreeView [merged]
#213 - feat(planning): Add Generate Task Breakdown button to DiscoveryProgress [merged]
#214 - feat(planning): Add TaskReview component for task approval workflow [merged]
#215 - feat(dashboard): Add phase-aware task view integration (#016-6) [merged]
#461 - feat(web-ui): PROOF9 requirements list, detail, and dashboard widget (#458) [closed]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Extend the Task model with a requirement_ids list field from backend dataclass through API response to frontend TypeScript interface
• Create a shared SWR-based hook for fetching all PROOF9 requirements to enable efficient client-side lookups without N+1 API calls
• Display compact requirement badges on TaskCard with the first requirement shown and a "+N" overflow indicator, linked to the proof detail page
• Show full requirement details (ID, title, glitch type) in TaskDetailModal with clickable links to requirement pages

Design Choices

Design Choice 1: Which requirements system to link tasks to?

Options Considered:

1. Create a new PRD section parsing system to extract structured requirements from markdown
2. Use existing PROOF9 requirements which already have full API support and structured data

Chosen Option: 2

Rationale: Link tasks to PROOF9 requirements since they already provide the necessary structure (id, title, glitch_type) and API endpoints, avoiding the need to build a new parsing/storage layer.

Design Choice 2: How to fetch requirement details for TaskCard without N+1 API calls?

Options Considered:

1. Make individual API calls for each requirement on each card
2. Denormalize requirement title and glitch_type directly onto the Task model
3. Use a shared SWR cache that fetches all requirements once, then lookup by ID client-side

Chosen Option: 3

Rationale: Create a shared SWR hook for the requirements list, enabling efficient client-side lookup while keeping the Task model normalized.

Design Choice 3: How to display multiple requirements on TaskCard?

Options Considered:

1. Display all requirements as separate badges
2. Show the first requirement badge plus a "+N" indicator for additional requirements
3. Show only a count badge linking to the detail modal

Chosen Option: 2

Rationale: Show the first requirement as a full badge with a "+N more" indicator if additional requirements exist, balancing information density with card compactness.

Design Choice 4: URL format for requirement links?

Options Considered:

1. Implement hash-based anchors as suggested in ticket (e.g., /proof#REQ-042)
2. Use existing /proof/{req_id} path routing pattern

Chosen Option: 2

Rationale: Use the existing /proof/${req_id} path pattern to maintain consistency with established routing conventions.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Backend Data Model Extension

Extend the Task data model through all backend layers to support linking tasks to PROOF9 requirements. This phase modifies the core dataclass, API serialization, and database schema.

Task 1: Add requirement_ids to Task Dataclass

Add the new field to the core Task model used by the workspace/v2 system.

• Update codeframe/core/tasks.py: Add requirement_ids: list[str] = field(default_factory=list) to the Task dataclass alongside existing fields like depends_on
• Follow the same pattern as depends_on which is already a list of string IDs

Task 2: Update TaskResponse Pydantic Model

Expose the new field through the API serialization layer.

• Update codeframe/ui/routers/tasks_v2.py: Add requirement_ids: list[str] = [] to the TaskResponse Pydantic model
• Ensure the field is populated in list_tasks, get_task, and update_task response construction

Task 3: Update Database Schema and Queries

Persist the requirement_ids field in SQLite storage.

• Update codeframe/persistence/ or the relevant task storage module to include requirement_ids column (stored as JSON array, following the pattern of other list fields)
• Modify INSERT/UPDATE/SELECT queries in the task repository to handle the new field
• Add migration or schema update logic if the codebase uses versioned migrations

🤖 Prompt for AI agents

Extend the backend Task data model to support a `requirement_ids` field through
the dataclass, API, and database layers.

- In `codeframe/core/tasks.py`, add `requirement_ids: list[str] =
field(default_factory=list)` to the `Task` dataclass, following the same pattern
as the existing `depends_on` field
- In `codeframe/ui/routers/tasks_v2.py`, add `requirement_ids: list[str] = []`
to the `TaskResponse` Pydantic model and ensure it is populated in `list_tasks`,
`get_task`, and `update_task` response construction
- In `codeframe/persistence/` (or the relevant task storage module), add a
`requirement_ids` column stored as a JSON array, following the pattern of other
list fields; update all INSERT/UPDATE/SELECT queries accordingly, and add
migration or schema update logic if the codebase uses versioned migrations

Phase 2: Frontend Types and Shared Data Layer

Update TypeScript types and create a shared hook for efficient requirement data access.

Task 1: Update Task TypeScript Interface

Extend the frontend type to match the updated API response.

• Update web-ui/src/types/index.ts: Add requirement_ids?: string[] to the Task interface
• No changes needed in web-ui/src/lib/api.ts as the axios client passes through response objects directly

Task 2: Create Shared Requirements Lookup Hook

Implement a custom hook that fetches and caches all requirements for efficient lookup by ID.

• Create web-ui/src/hooks/useRequirementsLookup.ts (or add to existing hooks directory)
• Use SWR with proofApi.listRequirements(workspacePath) as the fetcher
• Return a lookup function or Map that retrieves a ProofRequirement by ID
• Handle loading and error states appropriately
• This hook will be consumed by both TaskCard and TaskDetailModal

🤖 Prompt for AI agents

Update the frontend TypeScript type for `Task` and create a shared SWR-based
hook for looking up PROOF9 requirements by ID.

- In `web-ui/src/types/index.ts`, add `requirement_ids?: string[]` to the `Task`
interface; no changes are needed in `web-ui/src/lib/api.ts`
- Create `web-ui/src/hooks/useRequirementsLookup.ts`:
  - Use SWR with `proofApi.listRequirements(workspacePath)` as the fetcher
  - Return a lookup function or Map that retrieves a `ProofRequirement` by ID
  - Handle loading and error states appropriately
  - This hook will be shared by both `TaskCard` and `TaskDetailModal`

Phase 3: UI Component Updates

Implement the visual requirement badges on TaskCard and detailed requirement display in TaskDetailModal.

Task 1: Update TaskCard with Requirement Badges

Display requirement linkage on task cards with clickable badges.

• Update web-ui/src/components/tasks/TaskCard.tsx:
  • Import Link from Next.js and the shared requirements lookup hook
  • Add a new UI section (near the status badge or below the title) for requirement badges
  • For each requirement_id, look up the requirement to get title/glitch_type
  • Render the first requirement as a Badge with outline variant, containing a shortened ID (e.g., first 8 chars)
  • Add a glitch type indicator: either a small icon or muted text suffix showing the glitch type
  • Wrap the badge in a Link component pointing to /proof/${encodeURIComponent(reqId)}
  • If more than one requirement exists, render a "+N" indicator (could be a secondary muted badge)
  • Conditionally render the entire requirements section only when requirement_ids?.length > 0
  • Use existing Hugeicons (not lucide-react) for any icons needed

Task 2: Update TaskDetailModal with Requirement Details

Show expanded requirement information in the task detail view.

• Update web-ui/src/components/tasks/TaskDetailModal.tsx:
  • Import the shared requirements lookup hook
  • Add a new "Requirements" section in the modal body (below description or metadata row)
  • For each requirement_id in the task, display:
    • Requirement ID as a clickable link to /proof/${reqId}
    • Requirement title
    • Glitch type (if present) styled as a muted caption or small badge
  • Handle empty state: omit the section entirely when no requirements are linked
  • Handle loading state while requirements data is being fetched via the shared hook
  • Follow existing modal styling patterns (use consistent spacing, typography classes)

🤖 Prompt for AI agents

Implement requirement badge display on `TaskCard` and expanded requirement
details in `TaskDetailModal` using the shared lookup hook created in Phase 2.

**TaskCard** (`web-ui/src/components/tasks/TaskCard.tsx`):
- Import `Link` from Next.js and the shared `useRequirementsLookup` hook
- Add a requirement badges section near the status badge or below the title;
render it only when `requirement_ids?.length > 0`
- For each `requirement_id`, look up the requirement to get its title and
glitch_type
- Render the first requirement as a `Badge` with `outline` variant showing a
shortened ID (e.g., first 8 chars), with a glitch type indicator as a small icon
or muted text suffix
- Wrap the badge in a `Link` pointing to `/proof/${encodeURIComponent(reqId)}`
- If more than one requirement exists, render a "+N" muted secondary badge as an
overflow indicator
- Use existing Hugeicons (not lucide-react) for any icons

**TaskDetailModal** (`web-ui/src/components/tasks/TaskDetailModal.tsx`):
- Import the shared `useRequirementsLookup` hook
- Add a "Requirements" section in the modal body (below description or metadata
row)
- For each `requirement_id`, display: the requirement ID as a clickable link to
`/proof/${reqId}`, the requirement title, and the glitch type (if present) as a
muted caption or small badge
- Omit the section entirely when no requirements are linked
- Show a loading state while requirement data is being fetched
- Follow existing modal styling patterns for consistent spacing and typography

Research

The codebase has a workspace-based task system (codeframe/core/tasks.py) with a v2 REST API (codeframe/ui/routers/tasks_v2.py) serving a React/Next.js frontend. Tasks currently have a prd_id field linking to whole PRD documents, but no linkage to individual requirements. The PROOF9 requirements system (/api/v2/proof/requirements) provides structured requirement data with id, title, glitch_type, and other fields, accessible via proofApi on the frontend. The Badge component has established variants for task statuses and can be extended for requirement display.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Extend the backend Task data model to support a `requirement_ids` field through
the dataclass, API, and database layers.

- In `codeframe/core/tasks.py`, add `requirement_ids: list[str] =
field(default_factory=list)` to the `Task` dataclass, following the same pattern
as the existing `depends_on` field
- In `codeframe/ui/routers/tasks_v2.py`, add `requirement_ids: list[str] = []`
to the `TaskResponse` Pydantic model and ensure it is populated in `list_tasks`,
`get_task`, and `update_task` response construction
- In `codeframe/persistence/` (or the relevant task storage module), add a
`requirement_ids` column stored as a JSON array, following the pattern of other
list fields; update all INSERT/UPDATE/SELECT queries accordingly, and add
migration or schema update logic if the codebase uses versioned migrations
===============================================================================

Task: 2

Update the frontend TypeScript type for `Task` and create a shared SWR-based
hook for looking up PROOF9 requirements by ID.

- In `web-ui/src/types/index.ts`, add `requirement_ids?: string[]` to the `Task`
interface; no changes are needed in `web-ui/src/lib/api.ts`
- Create `web-ui/src/hooks/useRequirementsLookup.ts`:
  - Use SWR with `proofApi.listRequirements(workspacePath)` as the fetcher
  - Return a lookup function or Map that retrieves a `ProofRequirement` by ID
  - Handle loading and error states appropriately
  - This hook will be shared by both `TaskCard` and `TaskDetailModal`
===============================================================================

Task: 3

Implement requirement badge display on `TaskCard` and expanded requirement
details in `TaskDetailModal` using the shared lookup hook created in Phase 2.

**TaskCard** (`web-ui/src/components/tasks/TaskCard.tsx`):
- Import `Link` from Next.js and the shared `useRequirementsLookup` hook
- Add a requirement badges section near the status badge or below the title;
render it only when `requirement_ids?.length > 0`
- For each `requirement_id`, look up the requirement to get its title and
glitch_type
- Render the first requirement as a `Badge` with `outline` variant showing a
shortened ID (e.g., first 8 chars), with a glitch type indicator as a small icon
or muted text suffix
- Wrap the badge in a `Link` pointing to `/proof/${encodeURIComponent(reqId)}`
- If more than one requirement exists, render a "+N" muted secondary badge as an
overflow indicator
- Use existing Hugeicons (not lucide-react) for any icons

**TaskDetailModal** (`web-ui/src/components/tasks/TaskDetailModal.tsx`):
- Import the shared `useRequirementsLookup` hook
- Add a "Requirements" section in the modal body (below description or metadata
row)
- For each `requirement_id`, display: the requirement ID as a clickable link to
`/proof/${reqId}`, the requirement title, and the glitch type (if present) as a
muted caption or small badge
- Omit the section entirely when no requirements are linked
- Show a loading state while requirement data is being fetched
- Follow existing modal styling patterns for consistent spacing and typography

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!