Add dow --version flag and fix man-page control-line text loss (v2.0.3)

Two defects surfaced during a fresh-venv install verification of v2.0.2:

- There was no `dow --version` / `dow -V`, even though the version already
  fed the man-page header. Added a top-level eager Typer option.
- The roff generator did not guard wrapped prose lines that begin with `'`
  or `.` (a roff control-line prefix), so troff silently dropped such
  sentences (e.g. init's "'dow commit' to capture v1 ...") and warned
  `macro 'dow' not defined`. `_roff` now protects them with a zero-width
  `\&`. Regenerated the packaged man page (its header was a stale 0.1.0).

Adds tests/test_manpage.py to pin both fixes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: theflyingrahul

CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to dow are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and dow adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [2.0.3] - 2026-07-11
+
+### Added
+- **`dow --version` / `dow -V`.** A top-level flag now prints the installed
+  version and exits. The version was already computed for the man-page header
+  but was not reachable from the command line.
+
+### Fixed
+- **Man page dropped any prose line that began with `'` or `.`.** A wrapped
+  documentation sentence starting with an apostrophe or period (e.g. init's
+  "'dow commit' to capture v1 ...") is a roff *control* line, so troff silently
+  swallowed it and warned `macro 'dow' not defined`. The roff generator now
+  guards such lines with a leading zero-width `\&`, so every sentence renders.
+  Regression tests added (`tests/test_manpage.py`).
+- **Regenerated the packaged man page** (`man/dow.1`): its header showed a stale
+  `dow 0.1.0` and predated the escaping fix.
+
 ## [2.0.2] - 2026-07-11
 
 ### Changed

dow/__init__.py

@@ -1 +1 @@
-__version__ = "2.0.2"
+__version__ = "2.0.3"

dow/cli.py

@@ -435,8 +435,16 @@ def _dow_version() -> str:
 
 
 def _roff(text: str) -> str:
-    """Escape dynamic text for a roff man page (backslashes and hyphens)."""
-    return text.replace("\\", "\\\\").replace("-", "\\-")
+    """Escape dynamic text for a roff man page.
+
+    Doubles backslashes and escapes hyphens, and protects any line that begins
+    with ``.`` or ``'`` - which roff treats as a control line - with a leading
+    zero-width ``\\&`` so wrapped prose (e.g. a sentence starting with
+    ``'dow commit'``) is not silently swallowed by troff.
+    """
+    text = text.replace("\\", "\\\\").replace("-", "\\-")
+    lines = text.split("\n")
+    return "\n".join("\\&" + ln if ln[:1] in (".", "'") else ln for ln in lines)
 
 
 def _command_usage(cmd, name: str) -> str:
@@ -591,6 +599,26 @@ def _print_banner() -> None:
         pass  # decorative only; never let a legacy console break the command
 
 
+def _version_callback(value: bool) -> None:
+    if value:
+        report.console.print(f"dow {_dow_version()}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _main(
+    version: bool = typer.Option(
+        None,
+        "--version",
+        "-V",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the dow version and exit.",
+    ),
+) -> None:
+    """Drift Observation Workbench - track how your AI's behavior changes across versions."""
+
+
 def main() -> None:
     # UTF-8 output so the banner and box-drawing art survive redirection on Windows
     # (a piped stdout otherwise defaults to cp1252 and cannot encode the glyphs).

man/dow.1

@@ -1,4 +1,4 @@
-.TH DOW 1 "2026-07-10" "dow 0.1.0" "Drift Observation Workbench"
+.TH DOW 1 "2026-07-11" "dow 2.0.3" "Drift Observation Workbench"
 .SH NAME
 dow \- track how your AI's behavior changes across versions
 .SH SYNOPSIS
@@ -18,7 +18,7 @@ Creates specs/<name>.yaml from a starter template and, if it does not exist yet,
 an evals.py with a couple of example evaluators. Pass a name to choose the spec
 (the default is 'summarization'); the spec's name and the file are kept in sync.
 Edit the spec to describe your prompt, model, sampling, and evaluation, then run
-'dow commit' to capture v1. This only writes starter files \- there is no staging
+\&'dow commit' to capture v1. This only writes starter files \- there is no staging
 area, index, or refs, and it refuses to overwrite an existing spec.
 .PP
 Arguments:
@@ -457,4 +457,3 @@ A vLLM OpenAI-compatible server, local or remote. Set VLLM_BASE_URL (default htt
 .PP
 .SH SEE ALSO
 Run \fBdow help\fR or \fBdow help \fICOMMAND\fR for interactive help.
-

tests/test_manpage.py

@@ -0,0 +1,45 @@
+"""Man page + version surface: guard the roff generator and `dow --version`.
+
+Regression coverage for two defects found during a v2.0.2 install verification:
+
+1. A wrapped doc line beginning with ``'`` or ``.`` is a roff control line, so
+   troff silently dropped it (e.g. init.txt's "'dow commit' to capture v1 ..."
+   sentence vanished from `man dow`). `_roff` now protects such lines with a
+   leading zero-width ``\\&``.
+2. There was no ``dow --version`` flag even though the version feeds the man
+   page header; it is now a top-level eager option.
+"""
+from typer.testing import CliRunner
+
+from dow.cli import _dow_version, _render_manpage, _roff, app
+
+runner = CliRunner()
+
+
+def test_roff_protects_leading_control_characters():
+    # Lines that begin with a roff control char get a zero-width guard.
+    assert _roff("'dow commit' to capture v1").startswith("\\&'")
+    assert _roff(".PP is not a real macro here").startswith("\\&.")
+    # Ordinary prose is untouched (apart from hyphen/backslash escaping).
+    assert _roff("ordinary line") == "ordinary line"
+    # Multi-line text is guarded line by line.
+    out = _roff("first line\n'second starts with quote")
+    assert out.splitlines()[1].startswith("\\&'")
+
+
+def test_manpage_has_no_unprotected_control_line_from_prose():
+    page = _render_manpage()
+    # The init sentence that troff used to swallow must survive, guarded.
+    assert "'dow commit' to capture v1" in page
+    assert "\\&'dow commit' to capture v1" in page
+    # No line may start with an apostrophe followed by a letter (that is the
+    # exact shape troff misreads as an undefined macro call).
+    for line in page.splitlines():
+        assert not (line[:1] == "'" and line[1:2].isalpha()), line
+
+
+def test_version_flag_prints_version():
+    for flag in ("--version", "-V"):
+        result = runner.invoke(app, [flag])
+        assert result.exit_code == 0
+        assert _dow_version() in result.stdout