Feature: Computed dueStatus field + MCP tool-description shape hints

[manucompiles]

What we're building

Phase 3 of the MCP+UI proposal (v2.10.3), two clubbed items:

Feature 9 - computed dueStatus: a server-computed, read-only field on every task, returned alongside deadline. Values: overdue, today, this_week, later, none. Computed in the API layer relative to today (no DB schema change). Flows through MCP automatically; the web UI adopts it for forward-compat.

Feature 8 - tool-description shape hints: append a one-line "Returns: ..." sentence to each of the 16 MCP tool descriptions.

Scope

• Backend: TaskModel gains a [NotMapped] computed DueStatus property + a pure static ComputeDueStatus(DateTime? deadline, DateTime today) helper. Auto-serializes through all 7 task-returning actions. No DB schema change.
• Buckets: none / overdue / today / this_week (after today through the upcoming Sunday) / later. Server-local DateTime.Today, date-only compare.
• MCP: dueStatus on the Task interface; a "Returns:" shape hint on all 16 tool descriptions.
• Frontend: dueStatus on the Task type + fixtures. Existing deadline color thresholds unchanged (different by design).

Plan

docs/plans/_archive/P61-due-status-and-tool-hints.md

Outcome

What was built:

• TaskModel: [NotMapped] computed DueStatus getter + pure static ComputeDueStatus(deadline, today). Buckets overdue / today / this_week (through the upcoming Sunday) / later / none, date-only, server-local. Auto-serializes through all 7 task-returning actions; no schema change.
• MCP: dueStatus on the Task type; all 16 tool descriptions got a "Returns:" shape sentence.
• Frontend: dueStatus on the Task type + fixture; deadline color logic unchanged.
• Deploy: set TZ=Asia/Kolkata (new SERVER_TZ var) on the backend service so DateTime.Today matches the user's local day.

Verified:

• 74 backend / 66 MCP / 47 frontend tests; clean typecheck and build.
• Deployed to the phone; live curl confirmed all 5 dueStatus buckets correct after the TZ fix (which a first live run caught - a real timezone bug unit tests could not see).
• Deferred: Step 5.3 hands-on Claude spot-check (user-only, non-blocking).

Issues raised during this work:

• GCP deploy: set TZ so computed dueStatus uses a correct local day #62 - set TZ on the GCP deploy for correct demo dueStatus (review R1). R2 (bucket string contract duplicated across C#/TS) intentionally left as-is.

[manucompiles]

Issues raised from code review:

• GCP deploy: set TZ so computed dueStatus uses a correct local day #62 - set TZ on the GCP deploy so its computed dueStatus uses a correct local day (R1)

R2 (dueStatus string values duplicated across C#/TS) was reviewed and intentionally left as-is - stable 5-value enum, codegen would be over-engineering. No blocks; review otherwise clean.

[manucompiles]

Documentation updated (synced during execute, verified now):

• docs/architecture.md - dueStatus as a response-only computed field on the Tasks model (not a column)
• docs/engineering-guidelines.md - the [NotMapped] computed-response-field + pure-static-helper pattern (v2.10.3)
• docs/product-design.md - tasks now expose a server-computed due bucket
• CHANGELOG.md - v2.10.3 section (dueStatus + 16 tool 'Returns:' hints)
• docs/tests/coverage.md - counts 74/66/47 + ComputeDueStatus + dueStatus-shape checklists

README needs nothing (dueStatus is not a user-visible UI feature).

Follow-up: writing /learnings server-local-time-vs-utc (the TZ bug). Ready for /ship after.

[manucompiles]

Release: https://github.com/hydraInsurgent/Tasklog/releases/tag/v2.10.3