From bfabb391e487e274091eefda2bca5673c725c057 Mon Sep 17 00:00:00 2001 From: Daniel Ari Friedman <6911384+docxology@users.noreply.github.com> Date: Thu, 12 Nov 2026 10:44:18 -0800 Subject: [PATCH] docs(todo): refresh the handoff with the landed merges, the stuck pin and locked CI --- TO-DO.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/TO-DO.md b/TO-DO.md index 04179f9..822a7b0 100644 --- a/TO-DO.md +++ b/TO-DO.md @@ -1,6 +1,6 @@ # TO-DO — Knowledge-Engineering documentation pass -Last reviewed: 2026-11-12 (composable gate entry point) after 2026-11-02 (canonical-ontology pointer pass) and 2026-08-02 (docs-deep review; see `REVIEW_LOG_2026-08-02.md`) +Last reviewed: 2026-11-12 (handoff refresh after the Publishing, pin-schema and sidecar merges; GNN pin and CI evidence rechecked) after 2026-11-12 (composable gate entry point), 2026-11-02 (canonical-ontology pointer pass) and 2026-08-02 (docs-deep review; see `REVIEW_LOG_2026-08-02.md`) Sections: - **Minor** — typo, broken link, formatting, small cleanups. @@ -28,7 +28,11 @@ Sections: - [x] **Improve `.aii/config.yaml` description** — `repo.description` was a bare Zenodo URL + DOI; replaced with a human-readable description and registered all top-level and area doc artifacts. ✓ commits `94ff9a7`, `2c2660d` - [x] **Harden PDF_Scrape entrypoint behavior** — `streamingExport.py` prompted at import time and `manager.py` executed at import. Now: lazy export configuration (import-safe), `if __name__ == "__main__"` guard, and failure logs include the exception message. Verified end-to-end in a throwaway venv (257-record run via stdin). ✓ commit `5bb023f` (fix: guard manager entrypoint and make streaming export configuration lazy) - [x] **Point at the canonical ontology home** — `Ontology_Snapshot/` is a frozen December 2022 export, so the README, `docs/provenance.md`, and the area README now name [`Active_Inference_Ontology`](https://github.com/ActiveInferenceInstitute/Active_Inference_Ontology) as the published home: current v5 release (May 25, 2023, 429 terms) with stable identities and typed relations, the archived December 12, 2022 snapshot of the same 411-row export, and the GNN vocabulary bridge for `ActInfOntologyAnnotation` labels. 402 of the 408 terms in the snapshot appear verbatim in the v5 release the canonical repository publishes. The snapshot CSVs were not touched. Verified: the canonical paths exist on that repository's `main` branch, the term overlap was measured from the committed CSVs, and every relative link in the edited files resolves. ✓ commit `fbaefeb` -- [x] **Compose the gate into one entry point** — the archive checks moved into `.github/scripts/archive_checks.py` and the GNN job body moved out of `ci.yml` into `.github/scripts/gnn_conformance.py`; `.github/scripts/gate.py` is now the only command line, with separately runnable arms (`links`, `python`, `notebooks`, `checkpoints`, `archive`, `tests`, `gnn`, `fast`, `full`, `timings`). Both CI jobs run one arm each, so no check body is duplicated in the workflow, and the pin is validated against schema `gnn-importer-pin/v1` in code instead of two inline heredocs. The gate gained tests (`.github/scripts/tests/test_gate.py`) and a generated wall-time page (`docs/gate-timings.md`); `docs/RUN_GUIDE.md` and `docs/documentation-index.md` document them. ✓ 2026-11-12 +- [x] **Compose the gate into one entry point** — the archive checks moved into `.github/scripts/archive_checks.py` and the GNN job body moved out of `ci.yml` into `.github/scripts/gnn_conformance.py`; `.github/scripts/gate.py` is now the only command line, with separately runnable arms (`links`, `python`, `notebooks`, `checkpoints`, `archive`, `tests`, `gnn`, `fast`, `full`, `timings`). Both CI jobs run one arm each, so no check body is duplicated in the workflow, and the pin is validated against schema `gnn-importer-pin/v1` in code instead of two inline heredocs. The gate gained tests (`.github/scripts/tests/test_gate.py`) and a generated wall-time page (`docs/gate-timings.md`); `docs/RUN_GUIDE.md` and `docs/documentation-index.md` document them. ✓ PR #9, commit `7ab2b6b` (2026-11-12) +- [x] **Adopt the canonical GNN importer pin schema** — `.github/gnn-pin.json` now declares `schema: gnn-importer-pin/v1` and a `recorded` date, so the estate-wide reader no longer reports the pin as unversioned; the existing keys and values were left byte-identical. The pin body is still `v5.0.3` — see [Open](#open--deferred). ✓ PR #8, commit `a05864a` +- [x] **Check reference-style links on every line** — the archive-checks refactor dropped `re.MULTILINE` from `REFERENCE_LINK`, so a reference definition below a page's first line (e.g. `[appendix]: missing.md`) stopped being checked; the flag is restored and `test_gate.py` now covers both a missing and a resolving definition below a heading. ✓ PR #10, commit `438b281` +- [x] **Record the Publishing member contract and identity pins** — `docs/workflows/publishing.md` points at the ActiveInferenceJournal contract (revision `d8ec888a8f3051a66bed9af047ee4b206050bdce`) and carries the `name sha256` block for `record-identity.schema.json`, `scripts/gate/identity.py` and `.github/gnn-pin.json`; the `links` arm runs the copied module's `--verify-copy` for all three and `test_publishing.py` proves a drifted copy fails the docs gate. Digests were checked against the files (`identity: … matches publishing.md`). ✓ PR #11, commit `a6d282c` +- [x] **Correct the sidecar document paths** — `.aii/config.yaml` listed `.aii/docs/INTEGRATION.md` and `.aii/docs/AGENTS.md` under `docs:`, but the validator resolves entries relative to `.aii/`, so those pointed at `.aii/.aii/docs/…`; they are now `docs/INTEGRATION.md`, `docs/AGENTS.md`, `../docs/documentation-index.md` and `../docs/workflows/publishing.md`, and `aii_sidecar validate` reports `OK: .`. ✓ PR #12, commit `d5bf61c` ## Major @@ -39,10 +43,12 @@ Sections: --- -## Open / deferred (unchanged items) +## Open / deferred -None — every scoped finding from the 2026-08-02 review has been implemented. Future candidates (not scoped, noted for owners): +No scoped finding from the 2026-08-02 review is still open. Everything below is either newly found or deliberately deferred; each line names what blocks it and who clears it. -1. Rendered docs site with a static-site generator and CI (MkDocs/Jekyll) if the repo grows a library component. -2. Code modernization beyond the entrypoint fix: `dataImport.py`/`docResults.py` module-level file reads (relative paths by design), `formatFileId` edge cases. (`docResults1` legacy variant was removed on 2026-11-06.) -3. A `requirements.txt`/`pyproject.toml` for the PDF_Scrape tool if it is revived for active use. +1. **The GNN pin is still `v5.0.3`** — `.github/gnn-pin.json` records tag `v5.0.3`, revision `8f293d9ba810e6eda5c09842d9c7ed9ffa5f92c1`, while the estate cutover revision is `v5.1.0` = `75c834bd8519dc7b5adc4d24f16bf393cfd1ecdf` (`git ls-remote --tags` against `Generalized_Notation_Notation`, 2026-11-12). A bump is three coordinated edits — the pin's `tag`/`revision`/`recorded`, the `gnn-pin.json` digest in the [Publishing digest block](docs/workflows/publishing.md), and the pin tables in `.github/GNN.md` and `docs/RUN_GUIDE.md` — plus a green `python .github/scripts/gate.py gnn --install`. The `links` arm fails until the digest is refreshed, and `test_publishing.py` encodes that. That run needs a CPython 3.11–3.14 interpreter (recipe: [`docs/RUN_GUIDE.md`](docs/RUN_GUIDE.md#running-the-gnn-arm-locally)), because the pinned release declares `>=3.11,<3.15` and this host's default Python is 3.15.2. Owner: the maintainer who next touches the pin; nothing outside the repository blocks it. +2. **Hosted CI gives no verdict** — every workflow run fails before its jobs start: run `43244620261` (push to `main`, 2026-11-12) carries "The job was not started because your account is locked due to a billing issue" on both `docs and scripts` and `gnn conformance (pinned)`, and the same annotation appears on the pull-request runs for #11 and #12. Until the organisation's Actions billing is restored, a local `python .github/scripts/gate.py fast` is the only gate evidence and a merge cannot wait on a hosted check. Blocked outside this repository on ActiveInferenceInstitute GitHub billing; its owner clears it. +3. **Rendered docs site** with a static-site generator and CI (MkDocs/Jekyll) — deferred by the decision recorded under Major; unblock when the archive gains a build step or an installable package. Owner: repository maintainer. +4. **Code modernization beyond the entrypoint fix** — the `dataImport.py`/`docResults.py` reads that resolve `resc/params/*.csv` against the working directory (deliberate for a run-from-here archive) and `formatFileId` edge cases. Unscheduled: the scrapers only run against a PDF corpus that is not committed, so there is no reproducible test input. Owner: whoever revives PDF_Scrape. (`docResults1` legacy variant was removed on 2026-11-06, PR #6, commit `9b7658e`.) +5. **Packaging for the PDF_Scrape tool** — a `requirements.txt`/`pyproject.toml` if it is revived for active use; `git ls-files` tracks no packaging file today, which is also why the gate has no `lint` or `type` arm. Blocked on the same revival decision. Owner: whoever revives PDF_Scrape.