Epic-The-Musical-Timeline/docs/TODO.md

TODO

Durable backlog. Agents append here instead of leaving TODO comments in source. Small, specific, independently actionable. Remove only when actually done.

Now

• Verify every // TODO(verify) field in src/data/sample.ts (48 at bootstrap: saga names, singers, story times, Odyssey book/lines, motif descriptions, facts) before any content leaves mockup stage.

Next

• After a direction is chosen: decide whether the unused mockups are deleted or kept, and record the chosen direction in DESIGN.md.
• Add CI under .gitea/workflows/ (none exists): bun install --frozen-lockfile, bun test, bun run typecheck, bun run build; plus a check that AGENTS.md, CLAUDE.md, GEMINI.md and the docs/ paths exist and AGENTS.md is under 150 lines. Proposed, not added.

Someday

• Make bun dist/server.js work from any cwd (Bun 1.3.14 resolves bundled assets relative to cwd; try --asset-naming / naming, or re-check on a newer Bun). Today bun run start and Docker work around it.
• Derive src/server.ts routes and src/index.html cards from src/mockups/registry.ts instead of three hand-kept lists (tests catch drift today).
• Decide whether real lyrics may be shown (copyright question, deferred).

Recurring

• Maintain AGENTS.md:
  • Add a rule only in response to a real failure. When an agent repeatedly gets something wrong, that is a gap; add one line, ideally with a code example. Do not pre-empt hypothetical mistakes.
  • Update in the same PR as the convention change. A stale rules file is worse than none — it actively misleads.
  • Prune quarterly. Delete rules whose convention has changed or whose mistake no longer occurs.
  • Optional, cheap validation: run the same task twice in clean sessions, with and without the file, and compare steps and token use. This is how the published numbers were produced, and it is the only way to know your file is helping rather than costing 20% for nothing.

Known issues

• bun dist/server.js from the repo root crashes: TypeError: Bundled file "./index-….js" not found. Repro: bun run build && bun dist/server.js. Workaround: bun run start.
• Two mockups with byte-identical style.css fail bun run build with "Multiple files share the same output path" (reproduced by copying 01-editorial/style.css over 02-vertical-story/style.css). Identical main.ts files do not trigger it.
• docs/plans/001-timeline-mockups.md tells mockup agents to start bun dist/server.js, which hits the issue above; use bun run start instead.