feat: add external reference field to tasks

Open
  • Is something wrong?
#241 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
csharp
Domain
api, backend, database, frontend

Research direction

The payload names no source files, so locate the existing task model, its API contract and the database migrations yourself. The work spans the API, validator, migration and UI, and the duplicate-detection point is open, so settle its scope with the maintainer before coding. Done means an optional external reference can be set and read through the API, is validated and persisted by a migration, and the duplicate behaviour is decided and documented.

Written by the indexing model from the issue text.

Description

enhancement

Groomed 2026-10-14 — ready for implementation.

Waits for the monorepo move (#397). This changes the API, so it is built after the assistant moves into this repo and the MCP change ships in the same PR (checked by the integration and error-code tests).

Original Description

Problem

Tasks have no place for an external reference (GitHub issue number, incident link), so it ends up in the title.

Proposal

  • Add an optional external reference field to tasks (API, validator, migration, UI).
  • Consider duplicate detection when two tasks share the same reference.

Context

Found while using Claude via the MCP on 2026-10-12/13. Split from this issue's original scope: deeper subtasks moved to #243. The MCP side (duplicate-title warning) is tracked in nevridge/taskflow-assistant#4.

User Story

As a task owner, I want to record an optional external reference (such as a GitHub issue number or incident link) on a task, so that I can trace the task back to its source without putting that reference in the title.

Decisions made during grooming: duplicate detection is out of scope for this story; the field is free text up to 255 characters; the reference is shown on the task form, task detail page and tasks list, and is included in the tasks-page search; the journal todos section is unchanged.

Acceptance Criteria

  1. Create with a reference. Given the task form, when I create a task and enter an external reference, then the task is saved and the reference is returned when I fetch the task.
  2. Create without one. Given the task form, when I create a task and leave the reference blank, then the task is saved with no reference (null). The field is never required.
  3. Existing tasks. Given an existing task created before this change, when the system is upgraded, then the task still loads and shows no reference. No data is changed.
  4. Detail page. Given a task with a reference, when I open the task detail page, then the reference appears in the task's metadata.
  5. Edit. Given a task detail page, when I edit the reference and save, then the new value is stored and shown.
  6. Clear on update. Given a task with a reference, when I save an update that sends no reference (null), then the reference is cleared. This matches the existing full-replace update behavior.
  7. Whitespace. Given a create or update request, when the reference has leading or trailing whitespace, then the stored value is trimmed. When the reference is only whitespace, then it is stored as null.
  8. Format. Given a create or update request, when the reference is #241 or a URL, then it is accepted. No URL-format rule applies.
  9. Length. Given a create or update request, when the reference is exactly 255 characters, then it is accepted. When it is 256 characters, then the API rejects it with a validation error and nothing is saved.
  10. History. Given a task, when I add, edit, or clear its reference, then a history event of type ExternalReferenceChanged with a change summary is recorded. It appears in the task detail history panel and the journal history modal.
  11. No spurious events. Given a task, when I save an update with an unchanged reference (compared after trimming, ordinal string comparison), then no ExternalReferenceChanged event is recorded.
  12. Tasks list. Given tasks in the tasks list, when I view the list, then each task that has a reference shows it (read-only). Tasks without one show nothing in its place.
  13. Search. Given a task whose reference is GH-241, when I type GH-241 in the tasks-page search, then that task is in the results. The existing search over title and description keeps working.
  14. Client types. Given the API contract changes, when the typed client is regenerated with gen:api, then the create, update, and response types include the optional externalReference field.

Edge Cases

  • Existing clients, such as the MCP, that send updates without the new field will silently clear any stored reference under full-replace semantics. Coordinate with the MCP side (nevridge/taskflow-assistant) before or alongside release.
  • Case differences (gh-12 and GH-12). The ordinal compare treats them as different values, so changing only the case records a history event. Confirm that is acceptable.
  • Search matching. Should it be case-insensitive like the existing title and description search? Check that it behaves the same way.
  • Subtasks. Confirm the field behaves the same on them in the form, detail page, list, and search.
  • Very long values near 255 characters, such as pasted URLs. Check that they do not break the list or detail layout.

Out of Scope

  • Duplicate detection when two tasks share a reference. This means no unique index, no 409 response, no lookup endpoint, and no warning. It is a possible follow-up story.
  • Any change to the journal todos section (TodosSection). It does not show or edit the reference.
  • Editing the reference directly from the tasks list. The list display is read-only.
  • Deeper subtask nesting or re-parenting (#243).
  • The MCP-side duplicate-title warning and subtask listing (nevridge/taskflow-assistant#4, separate repo).
  • A data migration or back-fill of references for existing tasks.
  • Turning references into automatic links, or fetching data from GitHub or an incident tool.
  • A server-side search or filter by reference.
Dominant language
C#
Stars
1
Forks
0
Avg merge
2h 2m
Merged PRs (30d)
98

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from nevridge/TaskFlow

All issues in nevridge/TaskFlow

Similar issues

More C# issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.