fix(scripts): make cocotb_ref_model importable again (#1589)

* fix(scripts): make cocotb_ref_model importable again

The module fails at import:

  NameError: name 'EvalContext' is not defined

EvalContext is annotated on function parameters at lines 174 and 215 but the class
is defined at line 402. Python evaluates annotations at function-definition time
unless the module opts out, so the forward reference raises before argparse is
reached and the tool cannot run at all.

Adding `from __future__ import annotations` defers annotation evaluation and the
module loads. Afterwards it reaches its own argument parser and reports what it
needs:

  usage: cocotb_ref_model.py [-h] --ast-json AST_JSON --verilog VERILOG
                             --top-module TOP_MODULE [--use-cocotb] [--verbose]

Placement matters and is easy to get wrong: a __future__ import may be preceded
only by the module docstring, comments and blank lines. Inserting it between the
shebang and the docstring also makes the module load, but silently demotes the
docstring to an ordinary string expression and leaves __doc__ as None. It is
inserted after the docstring here, and ast.get_docstring confirms the docstring
survives.

Found by extending the pass-57/58 side-effect sweep to the EXEC bucket -- the last
12 scripts in the repository that had never been executed. No workflow references
this file, which is why the breakage went unnoticed.

* docs(now): record #1589 in the coordination anchor

now-sync-gate requires every PR to master to update docs/NOW.md.
This PR predates my knowing that; the entry describes what it
lands and states its honesty limits, in the file's existing shape.

---------

Co-authored-by: gHashTag <admin@t27.ai>

Author: gHashTag

docs/NOW.md

@@ -1,3 +1,22 @@
+# NOW — scripts: cocotb_ref_model is importable again (2026-08-01)
+
+Last updated: 2026-08-01
+
+## scripts: cocotb_ref_model is importable again (Closes #1592)
+
+- Branch: `fix/cocotb-forward-reference`
+- Issue: #1592
+- PR: #1589
+
+### Что легло
+- The module raised `NameError: name 'EvalContext' is not defined` at import: the class is annotated on parameters at lines 174 and 215 and defined at line 402. `from __future__ import annotations` defers annotation evaluation and the module loads.
+
+### Границы честности (BINDING)
+- Placement matters: a `__future__` import may be preceded only by the docstring, comments and blank lines. Putting it between shebang and docstring also loads the module but silently leaves `__doc__` as `None`. It goes after the docstring, confirmed with `ast.get_docstring`.
+- Found by running the EXEC bucket — the last 12 scripts in the repository never executed. No workflow references this file.
+
+---
+
 # NOW — ci: track the paper count the published version actually declares (2026-08-01)
 
 Last updated: 2026-08-01

scripts/cocotb_ref_model.py

@@ -20,6 +20,8 @@
 signedness.
 """
 
+from __future__ import annotations
+
 import argparse
 import json
 import os