Dataface Tasks

Make tasks server the primary master plans doc surface deprecating MkDocs

IDINFRA_TOOLING-MIGRATE_MASTER_PLANS_DOCS_PRIMARY_TO_TASKS_SERVER
Statuscompleted
Priorityp2
Milestonem1-ft-analytics-analyst-pilot
Ownersr-engineer-architect
Completed bydave
Completed2026-03-22

Problem

Two doc servers confuse contributors. Once the tasks server covers browsing + live status, MkDocs should become secondary or retired for master plans.

Longer-term end state (tracked across follow-on tasks): just tasks serve as the only local “plans site,” with navigation that mirrors milestones → workstreams → tasks/initiatives on the server, and eventual removal of just plans once parity and static export (if any) are settled.

Context

  • Dependency add-tasks-serve-command-and-plans-server is completed (PR #712 merged). The tasks server ships /status, /status.json, and /browse/ endpoints via FastAPI on port 8005.
  • MkDocs (just plans, port 8004) remains active for: Material theme search, macro-rendered content (macros.py), Mermaid diagrams, and the static deploy pipeline (.github/workflows/deploy-static-sites.yml → GCS bucket).
  • CI still runs mkdocs build -f tasks/mkdocs.yml for static hosting. Removing this requires a separate static-export story for the tasks server.
  • Operator /status UX: improve-tasks-serve-status-ui-for-operator-triage.
  • Rename + paths: rename-master-plans-tree-to-tasks — committed tree → tasks/, runtime state → <repo>/.tasks/, explicit TASKS_ROOT / --tasks-root instead of hard-coded tasks/ path math.

Possible Solutions

  • A — Docs-only migration: Update AGENTS.md, cli-reference.md, and justfile help to prefer just tasks serve for local browsing. Keep MkDocs for static deploy and as a secondary option. No code changes, no CI changes.
  • B — Remove MkDocs for plans: Delete tasks/mkdocs.yml and all MkDocs-specific assets after building a static export path for the tasks server. Requires CI pipeline changes.
  • Recommended: A now. B only after a static-export story ships and stakeholder sign-off.

Plan

  • [x] Audit feature gap: tasks server covers live status + markdown browse; MkDocs adds search, macros, Mermaid, and static deploy. Gap accepted for local dev workflow — search and macros are not needed for day-to-day task browsing.
  • [x] Update AGENTS.md to list just tasks serve as primary local workflow, MkDocs as secondary/static.
  • [x] Update tasks/tools/cli-reference.md to reflect primary status.
  • [x] Update justfile help text to label tasks server as primary and MkDocs as legacy.
  • [ ] (Future — out of scope) Adjust CI/publish pipeline once static export story exists.
  • [ ] (Future) README/CLAUDE entrypoints still to prefer just tasks serve explicitly (see Implementation Progress).

Implementation Progress

Audit: feature gap accepted

Feature Tasks Server MkDocs
Task status + live heartbeat Yes (/status) No
Markdown browse Yes (/browse/) Yes (rendered)
Search No Yes (Material)
Macros / Mermaid No Yes
Static deploy (GCS) No Yes

For local dev and operator workflows, live task status is the primary need. Search and macros are nice-to-haves used mainly for milestone/strategy docs, not daily task work. Gap accepted.

Changes made

  • AGENTS.md: Updated "Plans serving modes" to prefer just tasks serve as the primary local workflow, with just plans as secondary for static content.
  • cli-reference.md: Removed "separate from MkDocs" framing; stated tasks server is the primary local surface.
  • justfile: Updated help text to label tasks server as "Primary" and MkDocs as "Legacy".

Follow-up

  • README.md / CLAUDE.md still do not consistently list just tasks serve as the primary operator path for master plans — track as a small docs sweep or reopen scope.

QA Exploration

  • [x] N/A — docs-only changes, no UI affected

Review Feedback

  • [ ] Review cleared