Notes import: TODO.md and UPSTREAM.md as tasks
Every repo in the ecosystem keeps its open work in two markdown files:
TODO.md (what to do, - [ ] and - [x] items under headings) and
UPSTREAM.md (what it is waiting on in other repos, each item naming the
issue it filed). This module turns those lists into tasks, so the board can
hold the work that lives in files as well as the work that lives in GitHub.
Each top-level list item becomes one task, and it carries its why, not just its what (board #163):
- The title is the item's bold lead (
**Replica vs. a restarted host** (M1): …), else its first paragraph when that is short, else its first clause — cut at a;,—,:or a sentence end (never at "vs."), or before a parenthetical — so a title is never cut mid-sentence unless nothing else fits. - The body is the item's own words — the whole lead again when the title is only part of it, indented continuation lines, nested bullets, and unindented "lazy" continuation lines, as markdown reads them.
- Context: prose under the item's heading (outside any item) comes along as a quoted block — often the reason the list exists.
- Findings: given the review files it cites (
references), an item that names a finding —M1,F2,B3— gets that finding quoted from the review, with a link. The file is the one the item or its heading cites (a glob likereviews/0.5.0-review-\*.mdworks), or "the fifth re-review" →…re-review-5.md. - The source closes the body: the file and line, linked at the imported
commit when
repoUrlis given, and the heading path.
The CLI (virta project notes, bin/notes.ts, virta project onboard) fills in the path,
the repo's blob URL at HEAD, and the review files the notes cite. An open item arrives in backlog (a
roadmap item in freezer): it is acknowledged work, not something new
in the inbox. A done item — - [x], a leading ✅, a struck-through
~~lead~~, CLOSED / DONE, or "— done" — arrives closed. Every GitHub issue URL in the item
becomes a link tag: upstream:tosijs-ui#173 when the issue is in another
repo, github:12 when it is this project's own. The tags source:notes
and notes:todo / notes:upstream say where it came from.
Ids are deterministic — a hash of the item's text — so importing the same file again adds nothing (the hash stops at an item's first lazy line, as the first importer's did, so the richer parse kept every id), and a file that gained three items adds three tasks. An item whose wording changed is a new task; the old one stays, because the log never forgets and the file is not the truth once it has been imported (the same rule as GitHub issues after onboarding). Close the stale one on the board.
virta notes --project tosijs-virta --host https://… TODO.md UPSTREAM.md
The notes verb does the same for an agent, given the file's text.