feat(phase-2): narrative .docx memo with shared analytics + Layer 2 audit (#15)

What ships
- src/ycai/reports/docx.py: 9-section narrative memo per USER.md
  document-format discipline. Title, headline, coverage methodology,
  the agentic batch (capability heatmap), industry distribution, tech
  stack + OSS posture, six company spotlights, unanswered questions,
  reproducibility footer. Same analytics.py math as the deck. Same
  Layer 2 audit pre-write.
- src/ycai/reports/anti_hallucination.py: date-pattern stripping
  extended to YC-batch labels ('Winter 2026') and bare 4-digit years
  flanked by non-digits. The drift checker no longer surfaces years
  as numerical drift.
- src/ycai/cli.py: 'ycai report <run-dir>' now produces both deck +
  memo by default. --deck-only / --memo-only constrain.
- pyproject.toml: python-docx>=1.1 dep, mypy override extended to
  ycai.reports.docx (same untyped-import situation as ppt).

Tests: 4 new docx tests (149 total). Validates the .docx is a valid
zip with word/document.xml, contains 'coverage' + 'agents' in the
body, embeds >=3 chart images, aborts on a forbidden phrase smuggled
into a company rationale, builds even with empty quote candidates.

Real W26 memo captured at examples/output/report-w26-pr15-2026-05-01.docx.
4 chart PNGs (capability heatmap, industry bar, OSS pie, tech stack
bar). ~47 paragraphs. Layer 2 audit clean on the real run.

Phase 2 of the project plan is now shipped: depth=1 crawler (PR #11),
ECharts dashboard (PR #12), .pptx deck (PR #14), .docx memo (PR #15).
Phase 3 (Chrome extension) lives at the v1.0 milestone.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: RyanAlberts

CHANGELOG.md

@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Phase 2 — reports
 - **PR #14 — VC-style `.pptx` deck with anti-hallucination Layer 2.** New `src/ycai/analytics.py` is the single source of chart math, consumed by both the dashboard (ECharts JSON) and the deck (matplotlib PNG). New `src/ycai/reports/ppt.py` builds a 16-slide deck (cream/orange palette, sans/serif typography). Each chart is a matplotlib PNG anchored to the same Counter the dashboard used. `ycai report <run-dir>` produces `deck.pptx` from existing artifacts at zero LLM cost. New `src/ycai/reports/anti_hallucination.py`: forbidden-phrase scan + numerical-drift check + date-pattern stripping. Two prose streams audited separately — aggregate commentary gets full drift check, per-company taglines/rationales get forbidden-phrase only (Layer 1 already gated their source URLs). 24 new tests (145 total).
+- **PR #15 — narrative `.docx` memo.** New `src/ycai/reports/docx.py` builds a 9-section narrative memo per USER.md document-format discipline: title, headline, coverage methodology, the agentic batch (capability heatmap), industry distribution, tech stack + OSS posture, six company spotlights, unanswered questions, reproducibility. Same `analytics.py` math as the deck, same Layer 2 audit pre-write. Date-pattern stripping extended to YC-batch labels ("Winter 2026") and bare 4-digit years. `ycai report <run-dir>` now produces both `deck.pptx` and `report.docx`; `--deck-only` / `--memo-only` to constrain. 4 new tests (149 total).
 
 ## [0.1.0] — 2026-05-01
 

README.md

@@ -31,7 +31,7 @@ A Chrome extension wraps two flows: *(a)* analyze the whole batch, *(b)* deep-di
 |---|---|---|
 | 0 | Repo bootstrap, secrets hygiene, CI | ✅ shipped |
 | 1 | CLI + dashboard with anti-hallucination Layer 1 | ✅ **v0.1.0** |
-| 2 | Depth=1 crawler + ECharts dashboard + `.pptx` / `.docx` reports | 🟡 in progress |
+| 2 | Depth=1 crawler + ECharts dashboard + `.pptx` deck + `.docx` memo | ✅ shipped |
 | 3 | Chrome extension | ⬜ planned |
 
 See [CHANGELOG.md](CHANGELOG.md) for what 0.1.0 includes, [BACKLOG.md](BACKLOG.md) for the working backlog, and `docs/decisions/` for architecture decisions.

examples/README.md

@@ -4,7 +4,8 @@ Sanitized sample artifacts. Every commit goes through `make publish-check` so PI
 
 | File | What |
 |---|---|
-| [`output/deck-w26-pr14-2026-05-01.pptx`](output/deck-w26-pr14-2026-05-01.pptx) | **PR #14 VC-style deck — current best.** 16 slides, a16z-feel palette, matplotlib chart PNGs anchored to the same data the dashboard uses. Anti-hallucination Layer 2 ran before write (no forbidden phrases, no numerical drift). |
+| [`output/deck-w26-pr14-2026-05-01.pptx`](output/deck-w26-pr14-2026-05-01.pptx) | **PR #14 VC-style deck.** 16 slides, a16z-feel palette, matplotlib chart PNGs anchored to the same data the dashboard uses. Anti-hallucination Layer 2 ran before write. |
+| [`output/report-w26-pr15-2026-05-01.docx`](output/report-w26-pr15-2026-05-01.docx) | **PR #15 narrative memo.** 9 sections, ~47 paragraphs, 4 embedded chart PNGs. Headline finding, coverage methodology, capability heatmap with analysis, industry distribution, tech-stack/OSS-posture caveat, six company spotlights, unanswered questions. Layer 2 audit clean. |
 | [`output/dashboard-w26-pr12-2026-05-01.html`](output/dashboard-w26-pr12-2026-05-01.html) | **PR #12 dashboard — current best HTML.** Same W26 data, ECharts canvases (real heatmap, pies, bars). |
 | [`output/dashboard-w26-pr11-2026-05-01.html`](output/dashboard-w26-pr11-2026-05-01.html) | PR #11 dashboard with the depth=1 crawl but static CSS bars. Useful for comparing visual fidelity vs. PR #12. |
 | [`output/analyses-w26-pr11-2026-05-01.json`](output/analyses-w26-pr11-2026-05-01.json) | Source data for both PR #11 and PR #12 dashboards. 113/124 high-confidence. |

examples/output/report-w26-pr15-2026-05-01.docx

@@ -24,6 +24,7 @@ dependencies = [
   "anthropic>=0.40",
   "claude-agent-sdk>=0.1",
   "python-pptx>=1.0",
+  "python-docx>=1.1",
   "matplotlib>=3.7",
 ]
 
@@ -86,14 +87,14 @@ files = ["src/ycai"]
 # Third-party libraries without published type stubs. We pin to the public
 # constructor surface and otherwise treat their return types as Any.
 [[tool.mypy.overrides]]
-module = ["pptx.*", "matplotlib.*"]
+module = ["pptx.*", "matplotlib.*", "docx.*"]
 ignore_missing_imports = true
 
 # The deck builder is a thin wrapper over python-pptx whose API surface is
 # untyped (Presentation is a factory function, not a class). Keep strict
 # mode for everything else; relax just this module.
 [[tool.mypy.overrides]]
-module = "ycai.reports.ppt"
+module = ["ycai.reports.ppt", "ycai.reports.docx"]
 disallow_untyped_calls = false
 disallow_untyped_defs = false
 warn_return_any = false

pyproject.toml

@@ -118,7 +118,8 @@ def dashboard_cmd(
 @app.command("report")
 def report_cmd(
     run_dir: Path = typer.Argument(..., help="Run directory with coverage.json + analyses.json(l)."),
-    deck_only: bool = typer.Option(False, "--deck-only", help="Skip the .docx memo (Phase 2 PR #15)."),
+    deck_only: bool = typer.Option(False, "--deck-only", help="Skip the .docx memo."),
+    memo_only: bool = typer.Option(False, "--memo-only", help="Skip the .pptx deck."),
 ) -> None:
     """Generate the .pptx deck (and .docx memo when shipped) from existing artifacts.
 
@@ -149,23 +150,36 @@ def report_cmd(
         console.print(f"[red]✗ no analyses found in {run_dir}. Run with --enrich first.[/red]")
         raise typer.Exit(2)
 
+    from ycai.reports.docx import build_memo
     from ycai.reports.ppt import Layer2Failure, build_deck
 
-    deck_path = run_dir / "deck.pptx"
-    console.print("[cyan]→[/cyan] building deck.pptx (Layer 2 audit before write)…")
-    try:
-        build_deck(coverage, companies, analyses, output_path=deck_path)
-    except Layer2Failure as exc:
-        console.print(f"[red]✗ Layer 2 audit failed:[/red] {exc}")
-        for hit in exc.forbidden[:5]:
-            console.print(f"  [red]forbidden phrase '{hit.phrase}':[/red] {hit.excerpt}")
-        for drift in exc.drifts[:5]:
-            console.print(f"  [red]numerical drift '{drift.number}':[/red] {drift.excerpt}")
-        raise typer.Exit(5) from exc
-    console.print(f"[green]✓[/green] wrote {deck_path}")
+    if not memo_only:
+        deck_path = run_dir / "deck.pptx"
+        console.print("[cyan]→[/cyan] building deck.pptx (Layer 2 audit before write)…")
+        try:
+            build_deck(coverage, companies, analyses, output_path=deck_path)
+        except Layer2Failure as exc:
+            console.print(f"[red]✗ deck Layer 2 audit failed:[/red] {exc}")
+            for hit in exc.forbidden[:5]:
+                console.print(f"  [red]forbidden phrase '{hit.phrase}':[/red] {hit.excerpt}")
+            for drift in exc.drifts[:5]:
+                console.print(f"  [red]numerical drift '{drift.number}':[/red] {drift.excerpt}")
+            raise typer.Exit(5) from exc
+        console.print(f"[green]✓[/green] wrote {deck_path}")
 
     if not deck_only:
-        console.print("[yellow]⚠ .docx memo lands in PR #15.[/yellow]")
+        memo_path = run_dir / "report.docx"
+        console.print("[cyan]→[/cyan] building report.docx (Layer 2 audit before write)…")
+        try:
+            build_memo(coverage, companies, analyses, output_path=memo_path)
+        except Layer2Failure as exc:
+            console.print(f"[red]✗ memo Layer 2 audit failed:[/red] {exc}")
+            for hit in exc.forbidden[:5]:
+                console.print(f"  [red]forbidden phrase '{hit.phrase}':[/red] {hit.excerpt}")
+            for drift in exc.drifts[:5]:
+                console.print(f"  [red]numerical drift '{drift.number}':[/red] {drift.excerpt}")
+            raise typer.Exit(5) from exc
+        console.print(f"[green]✓[/green] wrote {memo_path}")
 
 
 @app.command("resume")

src/ycai/cli.py

@@ -50,6 +50,10 @@
     re.compile(r"\b\d{4}-\d{2}\b"),  # YYYY-MM
     re.compile(r"\b(?:in|since|as of) (?:19|20)\d{2}\b", re.IGNORECASE),
     re.compile(r"\b(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\s+\d{1,2},?\s+(?:19|20)\d{2}\b"),
+    # YC-batch labels like "Winter 2026" or "Summer 2025"
+    re.compile(r"\b(?:Winter|Spring|Summer|Fall)\s+(?:19|20)\d{2}\b"),
+    # Bare 4-digit year that looks like a year, with at least one non-digit on each side
+    re.compile(r"(?<![\d.-])(?:19|20)\d{2}(?![\d.-])"),
 )