# 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 like `reviews/0.5.0-review-\*.md` works), or "the fifth
  re-review" → `…re-review-5.md`.
- **The source** closes the body: the file and line, linked at the imported
  commit when `repoUrl` is 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.