This file is the map of LiveHD's documentation: where each kind of doc lives, and when to read which. It is intentionally thin — it links out rather than duplicating content. Read this first on a cold start.
| Layer | Lives in | Format | Read it when… |
|---|---|---|---|
| Current work | todo/ |
HTML | you want the open task list, a task's design, or to record/close a task |
| Default algorithm reference (draft) | external ../docs/docs/lhd/ |
Markdown → mkdocs | you need the current synthesis algorithm, conditional physical flow, reuse policy and research references |
| LiveHD & Pyrope reference | external ../docs → masc-ucsc.github.io/docs |
Markdown → mkdocs | you need the "why/what": language semantics, IR concepts, CLI usage, architecture |
| Agent how-to + rules | AGENTS.md |
Markdown | you are building/testing/debugging, or need the change-gated coding rules |
| Directory orientation | <dir>/README.md |
Markdown | you are editing a specific directory and need its layout / gotchas |
| This map | STRUCTURE.md |
Markdown | cold start: figuring out where something belongs |
Documents a human reads but does not edit are HTML (the todo/ hub; the
../docs site is Markdown source rendered to HTML by mkdocs). Documents that are
agent-only / agent-mostly are Markdown (AGENTS.md, directory README.mds,
this file).
todo/index.htmlis the hub: a bullet summary of every open task, grouped by topic (LiveHD, Pyrope, Verilog) and by Group N.- One file per task at
todo/<topic>/<id>.html. A task's full design lives in its page; cross-task dependencies are visible via shared Group letters. - Generated results and reproduction artifacts (reports, plots, metrics, logs,
snapshots and benchmark outputs) belong under ignored
repros/, never undertodo/or in Git. Task pages may link to these local artifacts; the links are available only in a checkout containing the corresponding results. - Lifecycle: a task page is deleted the moment the whole task lands. This layer is strictly current work — it carries no history (git does).
Every todo/<topic>/<id>.html follows the same shape so tasks read uniformly:
<h1>— the task badge + a short title, then a 1–2 sentence summary.- Depends on — a bullet list of the tasks this one needs first, each with a
one-sentence reason;
None.if it has no prerequisites. - Subtasks — pending — the work left, as labelled items
A,B,C, …, each with its own bullet list. The letter is a stable id. - Subtasks — landed — subtasks that were pending and have shipped, moved
here keeping their original letter (not deleted), until the whole task is
done and the page is removed.
None yet.if empty. - (optional) Design notes — reference / spec material kept at the bottom.
When a subtask ships, mark it and move it from pending to landed with the same letter; delete the whole page only once the task is fully complete. Skeleton:
<h1><strong class="item-id">1d</strong> Demand-driven emit + DCE</h1>
<p>Short summary…</p>
<h2>Depends on</h2>
<ul><li><a class="xref" href="1f.html">1f</a> — why, in one sentence.</li></ul>
<!-- or: <p>None.</p> -->
<h2>Subtasks — pending</h2>
<ul class="subtasks">
<li><strong>D — sea-of-nodes rewrite.</strong>
<ul><li>detail</li></ul></li>
</ul>
<h2>Subtasks — landed</h2>
<ul class="subtasks">
<li><strong>A — D1 range→sweep.</strong> <span class="status landed">landed</span></li>
</ul>- The draft algorithm reference (
../docs/docs/lhd/) describes the implemented default flow for expert readers and agents, with a separate conditional physical-flow chapter. Its maintenance appendix maps source evidence and local-document retirement candidates. Experimental algorithms, option catalogs and evaluation histories remain in their dedicated references. - The LiveHD guide (
../docs/docs/livehd/*) and the Pyrope language reference (../docs/docs/pyrope/*) are the canonical "why/what". The Pyrope pages are the de-facto language contract. - The language/IR contract stays conceptual. The algorithm reference may link to source evidence and component READMEs without duplicating their details. Change-gated: content changes need human confirmation.
- Build/test commands, sibling-repo paths, running Pyrope/Yosys tests, debugging
tips, and the Contracts section (compiler-warning policy, contract-test
immutability). Enforcement scripts live in
scripts/contracts/; baselines in.contracts/. - There is no in-repo
docs/contracts/directory — that role split into the../docsreference (human contract) andAGENTS.md(agent rules).
- A short Overview → Key files → Gotchas/debug hints for a directory, in
Markdown. Added or extended only when there is a demonstrated need (an agent
misread the structure, a file's purpose is non-obvious, or there's a debug
gotcha). Examples:
graph/README.md,upass/README.md,inou/attr/README.md,simlib/README.md.