diff --git a/CHANGELOG.md b/CHANGELOG.md index 7f14001..ba12d52 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index a347db0..8bc540a 100644 --- a/README.md +++ b/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). diff --git a/docs/assets/rocc-home.png b/docs/assets/rocc-home.png new file mode 100644 index 0000000..0ef329e Binary files /dev/null and b/docs/assets/rocc-home.png differ diff --git a/docs/assets/rocc-pipeline-health.png b/docs/assets/rocc-pipeline-health.png new file mode 100644 index 0000000..b0d26d4 Binary files /dev/null and b/docs/assets/rocc-pipeline-health.png differ