docs: record historical artifact qa

Author: mschwar

CURRENT_STATE.md

@@ -23,14 +23,16 @@ This repository is a small GitHub Pages static site that publishes a single oral
 
 - A local homepage QA snapshot passed `python scripts/check_homepage.py` and was then captured at desktop and mobile widths in a browser-rendered view.
 - The browser captures showed the heatmap image, page heading, and download link in the expected positions with no visible layout regressions.
+- Historical artifact governance passed non-UI QA: `python scripts/validate_repo.py`, Python script compilation, policy-doc discoverability checks, and `_config.yml` exclusion checks.
+- Live GitHub Pages QA returned HTTP 200, found the expected title and heatmap, and did not find a `README.CRAWL.html` link.
 
 ## Existing Commands
 
 | Command | Purpose | Result |
 | --- | --- | --- |
 | `python scripts/validate_repo.py` | Repo validation | Pass with warning about stale `README.CRAWL.md` |
-| `python scripts/render_heatmap.py` | Heatmap rebuild | Produces the published 1700 x 2200 PNG from the committed PDF source at 200 DPI |
-| `python scripts/check_homepage.py` | Homepage smoke test | Verifies the rendered homepage title, heading, heatmap image, alt text, download link, and the absence of README.CRAWL.html |
+| `python scripts/render_heatmap.py` | Heatmap rebuild | Currently blocked locally by Windows/MiKTeX `pdftoppm` temp/log permission errors |
+| `python scripts/check_homepage.py` | Homepage smoke test | Requires `_site/index.html` from a Jekyll build, or an explicit rendered HTML path or URL |
 | `Invoke-WebRequest https://mschwar.github.io/data-visualization/` | Live site verification | 200 OK |
 | `bundle exec jekyll build` | Local Jekyll build | Not run in this environment because Ruby was unavailable at audit time |
 
@@ -60,11 +62,12 @@ The pinned build path is now committed in-repo, so local build instructions are
 
 - Local GitHub Pages rendering is not reproducible from committed tooling in the current environment.
 - Local build execution still depends on having Ruby installed on the host.
+- Heatmap rebuild execution is currently blocked in this Windows environment by MiKTeX `pdftoppm` permission errors.
 - The historical source dataset that fed the original figure is still not published in this repo.
 - `README.CRAWL.md` remains as a historical artifact but is excluded from the public site.
 
 ## Immediate Next Moves
 
-1. QA the historical artifact governance branch by confirming `README.CRAWL.md` stays out of the public site and the new policy doc stays discoverable.
-2. Keep `scripts/render_heatmap.py` and `Figure2-Teeth_v4.1.pdf` in sync if the figure changes.
-3. Run `python scripts/check_homepage.py` against `_site/index.html` after a local build if you need a homepage smoke check.
+1. Start provenance refinement from [docs/agentic-first-buildout-plan.md](docs/agentic-first-buildout-plan.md).
+2. Track the follow-on fixes listed in [docs/agentic-first-buildout-plan.md](docs/agentic-first-buildout-plan.md).
+3. Keep historical artifacts documented in [docs/historical-artifacts.md](docs/historical-artifacts.md).

README.md

@@ -54,10 +54,23 @@ Run:
 
 ```bash
 python scripts/validate_repo.py
+```
+
+This checks for required files, obvious broken local references, key site metadata, and committed OS junk files.
+
+After rendering the site, run the homepage smoke test against the generated page:
+
+```bash
+bundle exec jekyll build
 python scripts/check_homepage.py
 ```
 
-This checks for required files, obvious broken local references, key site metadata, committed OS junk files, and the rendered homepage shape.
+You can also pass an explicit rendered HTML path or live URL:
+
+```bash
+python scripts/check_homepage.py _site/index.html
+python scripts/check_homepage.py https://mschwar.github.io/data-visualization/
+```
 
 ## Rebuild Locally
 

docs/agentic-first-buildout-plan.md

@@ -60,14 +60,15 @@ Start the remaining buildout here:
 
 ### 3. Historical artifact governance
 
-- Status: next.
+- Status: merged to main.
 - Goal: decide the final treatment of `README.CRAWL.md` and any other historical artifacts.
 - Merge boundary: docs and navigation only.
 - Verification: non-UI validation plus live site check that the artifact is not surfaced publicly.
 - Why third: it resolves repo hygiene after the public experience is stable.
 
 ### 4. Provenance refinement
 
+- Status: next.
 - Goal: tighten the provenance story around the source PDF, the published PNG, and any constraints on regeneration.
 - Merge boundary: documentation only.
 - Verification: non-UI link/file validation.
@@ -80,6 +81,46 @@ Start the remaining buildout here:
 - Verification: explicit non-UI command or GitHub Actions status.
 - Why last: deployment checks are most useful after the content and verification paths are stable.
 
+## Follow-On Feature List
+
+These are known missing or non-working items discovered during repo audit. Keep them as separate branches unless one is clearly part of the current feature.
+
+### A. Homepage Smoke-Test Documentation Fix
+
+- Problem: `python scripts/check_homepage.py` fails on a fresh checkout until `_site/index.html` exists.
+- Fix: document that the command requires `bundle exec jekyll build` first, or pass an explicit rendered HTML path or live URL.
+- Verification: run `python scripts/check_homepage.py <rendered-html-or-url>`.
+
+### B. Windows Heatmap Render Robustness
+
+- Problem: `python scripts/render_heatmap.py` fails in this Windows environment because MiKTeX `pdftoppm` cannot write its log/temp output under `AppData\Local`.
+- Fix: make the render script use a repo-local writable temp/output path or document the required MiKTeX environment variables.
+- Verification: run `python scripts/render_heatmap.py` and confirm `git diff -- oral-health-heatmap.png` is empty or expected.
+
+### C. Local Jekyll Bootstrap
+
+- Problem: local Jekyll builds remain unavailable in this environment because Ruby and Bundler are not installed.
+- Fix: add a Windows-friendly bootstrap note or setup script that installs/validates Ruby 3.3.4 and Bundler without changing the pinned CI build.
+- Verification: run `ruby -v`, `bundle -v`, and `bundle exec jekyll build`.
+
+### D. Live Site Verification
+
+- Problem: live GitHub Pages verification is currently ad hoc.
+- Fix: add a repeatable command or workflow step that checks the deployed URL after merge.
+- Verification: HTTP 200 plus expected title, heatmap image, and no `README.CRAWL.html` link.
+
+### E. Source Dataset Provenance
+
+- Problem: the source dataset behind the original heatmap is not published in this repository.
+- Addition: document whether the source dataset can be shared, cannot be shared, or lives in a controlled-access location.
+- Verification: non-UI documentation/link check.
+
+### F. Audit Document Refresh
+
+- Problem: the maturity score in `docs/agentic-overhaul/2026-05-audit.md` is stale after the build, CI, validation, and provenance improvements.
+- Fix: update scores and backlog so the audit reflects the current repo.
+- Verification: `python scripts/validate_repo.py`.
+
 ## Handoff Rules
 
 - Keep the plan discoverable by updating `CURRENT_STATE.md` when the next feature changes.