Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 13 additions & 7 deletions TO-DO.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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

Expand All @@ -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.
Loading