Credibility pass: authorship, show-the-product, and no hand-typed numbers

CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+This file tracks releases, not individual commits. Work merged to `main` after
+the last released version is listed under Unreleased. The version strings in
+`pyproject.toml` and `src/tens_hq/constants.py` still read `1.0.0` because no
+newer version has been cut; `git log` is the authority on what has shipped.
+
+## [Unreleased]
+
+### Added
+
+- Data-driven, site-specific manager action plan on Site Readiness.
+- Overdue-queue shading and a flagged weakest funnel step on the triage view.
+- Friendly column headers on leadership tables, from a shared label map.
+- Glossary, plus first-use expansions of ODLH, DLR, and QDLH.
+- Permissive `ruff` gate in CI and an advisory, pinned `pip-audit` scan; CI also
+  builds the demo container, boots it, and probes its health endpoint.
+
+### Changed
+
+- Planning controls moved above the navigation fold in the sidebar.
+- Ratio-forecast wording: formula id moved into a caption, the internal planning
+  floor relabeled, the `Hq = Hd` planning assumption disclosed, and the
+  unreachable-target guard described honestly (it does not trigger under the
+  current full-QDL assumption).
+- The two "ready hires" measures reconciled into distinct labels with coverage
+  captions.
+- Home hero KPIs re-cut for legibility: short labels, the gap stated in words.
+- Streamlit usage telemetry disabled, for an offline posture.
+- `run_demo.ps1` aligned to the runtime dependency list.
+- Validation counts derived from constants and covered by a drift test instead
+  of being hand-maintained; unused imports and locals removed.
+- README rule 2 now names all three synthetic contact surfaces, matching
+  ADR-024.
+
+### Fixed
+
+- Resource Network renders a zero-result empty state before its chart and table.
+- Generated outreach draft fields are read-only.
+- The log-scale x-axis on Source Performance is labeled.
+- The outreach queue is described as a read-only planning view; ADR-009 is
+  Proposed, not built.
+
+### Security
+
+- The site-name heading interpolation is HTML-escaped.
+- `pip-audit` is exact-pinned in CI, matching every other pinned dependency.
+
 ## [1.0.0] - 2026-07-22
 
 ### Added

README.md

@@ -1,21 +1,39 @@
 # ROCC — Recruiting & Outreach Control Center
 
-**A synthetic, aggregates-by-design workforce and outreach demonstration for an
-AbilityOne nonprofit operating context.** Part of the TENS HQ product family,
-alongside [GovCon Recompete Radar](https://github.com/CJud25/GovConRadar) and
-[ReconRadar](https://github.com/CJud25/ReconRadar).
+**Every record in this repository is synthetic by design — that is the
+governance point, not a limitation.** ROCC is a workforce and outreach control
+center for an AbilityOne nonprofit operating context: referral sources, sites,
+and contracts may be measured, and applicants never are. There is no hosted
+deployment — `.\run_demo.ps1` provisions a virtualenv and boots it locally.
+
+![ROCC Executive Command Brief: a 90-day planning indicator, gap to target,
+ready hires needed and at-risk site count as four KPI cards, a live "ready hires
+we can commit" slider with three simulated KPIs, and a portfolio trajectory
+chart](docs/assets/rocc-home.png)
+
+*The default page, screenshotted from a local run of this repository. Every
+figure on it is computed at run time by the deterministic synthetic generator;
+none of it is hand-entered. The synthetic-data banner sits in the sidebar on
+every page. The planning-indicator banner shown here also appears on Site
+Readiness and Ratio Forecast; Reports projects ratios too, but carries the
+human-review draft banner instead — the site readiness report it generates
+repeats the planning-indicator line inside the report body.*
 
 > **SYNTHETIC DEMO DATA — NOT FOR EMPLOYMENT OR COMPLIANCE DECISIONS.**
 > Every record is generated and fictional. No real applicant, employee, partner,
 > medical, disability, or eligibility data exists anywhere in this repository.
 
+Part of the TENS HQ product family, alongside
+[GovCon Recompete Radar](https://github.com/CJud25/GovConRadar) and
+[ReconRadar](https://github.com/CJud25/ReconRadar).
+
 ## The two rules (ADR-024)
 
 1. **Synthetic only, until sponsorship.** No real-data pathway ships. A real-data
    version happens only under employer sponsorship, in a separate trust boundary.
-2. **Aggregates by design.** Referral sources, sites, and contracts get measured —
-   **applicants never do.** No applicant-level rows, identifiers, or statuses
-   render anywhere (test-enforced). One documented exception: synthetic
+2. **Aggregates by design.** Referral sources, sites, and contracts may be
+   measured — **applicants never are.** No applicant-level rows, identifiers, or
+   statuses render anywhere (test-enforced). One documented exception: synthetic
    partner-organization **business contacts** may appear by name in three synthetic
    surfaces — the Resource Network contact table, the Outreach contact picker,
    and human-reviewed draft messages — they are B2B contacts, never applicants,
@@ -29,6 +47,16 @@ drafts), **Pipeline Health** (aggregate funnel counts, stage conversion, and
 time-in-stage — no people listed), source performance, a labeled ratio-forecast
 planning simulation, reports, and the privacy & governance statement.
 
+![ROCC Pipeline Health: synthetic referral, application, hire and referral-source
+totals, a stage funnel bar chart from Referred down to Eligibility Cleared, and a
+stage conversion table](docs/assets/rocc-pipeline-health.png)
+
+*Pipeline Health is where the second rule is easiest to check. The funnel is
+built from person-like synthetic records that never leave the data engine: the
+page renders counts, conversion rates, medians and shares, and
+`tests/test_ui_contract.py` fails the build if an applicant identifier or
+display label reaches a rendered frame.*
+
 ## Roadmap (future — none of this is built)
 
 - Contract-level recruiting attention driven by retention trends.
@@ -47,17 +75,50 @@ Privacy & Governance page.
 .\run_demo.ps1          # provisions a venv and launches the app
 ```
 
-or `pip install -r requirements.txt` then `streamlit run app.py` (Python 3.11+).
-Everything runs offline — the dataset is generated in memory, deterministically
-seeded. To materialize it as files for inspection:
+or `pip install -r requirements.txt` then `streamlit run app.py` (Python 3.11+;
+CI provisions 3.11). Everything runs offline — the dataset is generated in
+memory, deterministically seeded. To materialize it as files for inspection:
 `py scripts/generate_demo_data.py` (byte-stable across runs; the output directory
 is gitignored on purpose — a repo whose UI refuses per-person display does not
 ship browsable person-level files, even synthetic ones).
 
+The gate — the three commands CI runs on every push, ahead of an advisory
+dependency scan, a container build, and a health probe against the booted app:
+
+```powershell
+python -m pytest -q
+python -m ruff check .
+python scripts/validate_demo_data.py
+```
+
 - `docs/PRODUCT_BLUEPRINT.md` — the concept and its governance model.
 - `docs/PRIVACY_AND_GOVERNANCE.md` — the boundaries, in full.
 - `docs/decisions/` — the ADR lineage, including ADR-024.
 
+## How this was built
+
+I specified this product, cut it into gated slices, and verified each one; AI
+agents wrote most of the line-level code. The co-author trailers make the AI
+half of that split checkable — every non-merge commit in this history names an
+AI co-author. The other half is my account of the work, not a trailer.
+
+Every slice had to come back green on the repo's gate, and CI runs that gate on
+every push: `python -m pytest -q`, `python -m ruff check .`, and
+`python scripts/validate_demo_data.py`. CI has since grown around it — an
+advisory dependency scan, a container build, and a health probe against the
+booted app — so the pipeline a reader sees today is wider than the one the early
+slices cleared.
+
+An adversarial review pass then read what had landed and left its correction in
+the history as a commit of its own: `1b7b24c` ("writer-review fix"), a direct
+child of the initial release commit — that pass ran after the release, not
+before it.
+
+The history shows the AI co-authorship directly. The judgment calls are the part
+worth evaluating: where the slice boundaries fell, what this product refuses to
+compute, deleting the ADR-024 role gate rather than tuning it, and choosing to
+run an adversarial pass at all.
+
 ## License
 
 MIT — see [LICENSE](LICENSE).