Netlist review threads (async, in git)

CLAUDE.md

@@ -382,7 +382,9 @@ next to `Terms` under an instance node) with one deliberate asymmetry: a net
 entry carries no `child_id` and offers no "Show Equipotential" action — a
 net has no direction, and get_properties identifies it by name (`"net"`
 field) rather than by the provider-specific numeric id a term's
-`load_equipotential` request needs. See `NetlistTreeNetNode`/
+`load_equipotential` request needs. It does carry its `net_id`
+(`SNLNet::getID()`), only to anchor review threads (`getNetID()`; absent
+from older hosts). See `NetlistTreeNetNode`/
 `NetlistTreeBusNetBitNode` in `NetlistTree.h/.cpp`.
 
 Both `nets_response` and the `has_nets` flag filter out anonymous scalar
@@ -646,6 +648,19 @@ covers delayed selections, requests queued behind the swap and several
 viewers deterministically; the netlist there is "replaced" by itself, the
 worst case where every stale id still resolves.
 
+**Reviews** (full design: `docs/review_format.md`): threads on netlist
+objects, shared asynchronously through a directory committed with the
+design. The host owns the files (Python: `review.py`, `--review DIR`,
+`review=`; not yet `LocalSNLProvider`) and pushes `review_response` after
+each `root_response` and every write; the viewer sends `review_add_thread`
+(an anchor by ids: instance `id_path`, `term_id`, `net_id` from
+`nets_response`, optional `bit`) and `review_add_event` (reply, status), and
+a refused write comes back as `{"response":"error","request":"review_..."}`.
+Objects are identified by naja ids only, never by names: a thread is pinned
+to the netlist it was written on, stored in the review as a naja-if
+snapshot, and only drawn when the host resolves it `exact` on the loaded
+design (`other_snapshot` threads are listed, not drawn).
+
 `get_properties`/`properties_response` is a general name/value inspector for
 whatever object the UI asks about — an instance (including the top design
 itself), a term/pin, or a net — answered by both `LocalSNLProvider`
@@ -792,6 +807,25 @@ path the host read, used by the native "Open in Editor".
   `TraceStore::setColor()` refuses a near-black one (the convergence
   color, so shared gates stay unambiguous) and a near-white one (invisible
   on the white canvas).
+- **`ReviewStore`** — global static store (same pattern) for the review
+  threads the host last pushed (`review_response`; see "Reviews" under Wire
+  protocol): parsed threads, `writable`/`author`, the last refused write.
+  `instanceThreads()`/`termThreads()`/`netThreads()` match an object by
+  ids only (`id_path` + term/net id, optional bit), and only threads the
+  host resolved `exact`; `openCount()`/`openColor()` give the badges.
+  Builds the `review_add_thread`/`review_add_event` requests and their
+  anchors. Cleared on every fresh `root_response`/`root_loaded` (the host
+  pushes the review again after it).
+- **`ReviewView`** — the "Review" bottom-panel tab (open/all filter; a
+  thread's comments, Reply, Resolve/Won't Fix/Reopen, Select and Show in
+  Schematic for an exact one, the snapshot id for one on another netlist)
+  and the modal Add Comment dialog (`openComposer()`, drawn by
+  `renderComposer()` at the top level each frame), opened by
+  `commentMenuItem()` from the tree's instance/term/net menus and the
+  schematic's box and pin menus -- only shown when the host is writable.
+  The tree shows `[n]` open threads after a row, the schematic a numbered
+  disc on a box's corner (`InstanceShape::reviewOpen`, drawn through the
+  painter); hovering a tree row lists them.
 - **`SelectionStore`** — global static store (same pattern) for the one
   selection: an instance, by `InstancePath` (`{}` = top), or a schematic
   net, by `SchematicNetRef` (the pin its wire tree starts from: instance

CMakeLists.txt

@@ -103,6 +103,8 @@ set(CORE_SOURCES
   src/SelectionStore.cpp
   src/TraceStore.cpp
   src/TraceView.cpp
+  src/ReviewStore.cpp
+  src/ReviewView.cpp
   src/AppLogic.cpp
   ${IMGUI_SOURCES}
   # Read-only code view of the Source tab (SourceView).
@@ -265,6 +267,8 @@ if(NOT EMSCRIPTEN_BUILD)
       src/PropertiesStore.cpp
       src/SelectionStore.cpp
       src/TraceStore.cpp
+      src/ReviewStore.cpp
+      src/ReviewView.cpp
       src/GenerationProvider.cpp
       src/SchematicLayout.cpp
       src/SchematicInteraction.cpp

README.md

@@ -92,6 +92,8 @@ plus options, in any order. Their flags differ slightly:
 | `--yosys-src` | `--yosys-src` | Read Yosys `(* src *)` attributes, so Show Sources leads back to the RTL (Verilog only) |
 | `--source-root dir` | `--source-root dir` | Where to look for relative source paths (repeatable) |
 | `--source-map FROM=TO` | `--source-map FROM=TO` | Rewrite source paths recorded on another machine (repeatable) |
+| | `--review DIR`, `--author NAME` | Read and write review threads in DIR, a directory kept in git with the design ([format](docs/review_format.md)) |
+| | `--review DIR` alone, `--snapshot ID` | Open the netlist a review thread was written on, stored in the review |
 | | `--open` | Open the viewer in a browser |
 | | `--port N`, `--host H` | Where to serve (default `localhost:8081`) |
 
@@ -139,7 +141,13 @@ Cmd in the macOS desktop app (Ctrl in a browser, on any OS).
 | Click a box | Select the instance (also in the design tree) |
 | Click a wire | Select (highlight) its net |
 | Click a box's hierarchy glyph | Show / hide what is inside it |
-| Right-click | Menu: trace to driver, sources, properties, fit, clear |
+| Right-click | Menu: trace to driver, sources, properties, comment, fit, clear |
+
+In the design tree, right-click a row (an instance, a pin or a net) for its
+menu. With a review loaded (`--review DIR`), **Add Comment...** in these
+menus starts a review thread on that object; the **Review** tab lists the
+threads, to reply to them and resolve them. A tree row shows `[n]`, and a
+schematic box a numbered disc, for its open threads.
 
 | Keys (mouse over the schematic) | Action |
 |---|---|

REUSE.toml

@@ -21,12 +21,14 @@ path = [
   "CMakePresets.json",
   "README.md",
   "docs/demo.gif",
+  "docs/review_format.md",
   "docs/source_information.md",
   "python/README.md",
   "python/naja_schematic/__init__.py",
   "python/naja_schematic/__main__.py",
   "python/naja_schematic/_bundle.py",
   "python/naja_schematic/protocol.py",
+  "python/naja_schematic/review.py",
   "python/naja_schematic/server.py",
   "python/naja_schematic/session.py",
   "python/naja_schematic/static/index.html",
@@ -42,6 +44,7 @@ path = [
   "python/tests/test_design_generations.py",
   "python/tests/test_notebook.py",
   "python/tests/test_protocol.py",
+  "python/tests/test_review.py",
   "python/tests/test_source_references.py",
   "python/tests/test_transports.py",
   "python/tests/test_viewer_server.py",
@@ -92,6 +95,10 @@ path = [
   "src/SchematicView.h",
   "src/SelectionStore.cpp",
   "src/SelectionStore.h",
+  "src/ReviewStore.cpp",
+  "src/ReviewStore.h",
+  "src/ReviewView.cpp",
+  "src/ReviewView.h",
   "src/SourceStore.cpp",
   "src/SourceStore.h",
   "src/SourceView.cpp",
@@ -117,6 +124,8 @@ path = [
   "tests/FakeNetlistProvider.h",
   "tests/GUIDataTest.cpp",
   "tests/NetlistTreeTest.cpp",
+  "tests/ReviewStoreTest.cpp",
+  "tests/ReviewViewTest.cpp",
   "tests/GenerationProviderTest.cpp",
   "tests/SchematicInteractionTest.cpp",
   "tests/SelectionTest.cpp",