Repository navigation
gate: one entry point with arms, CI dedupe, and generated timings docs - #9
Merged
Merged
Conversation
Replace the monolithic check_archive.py with three focused modules and one command line: - archive_checks.py keeps the four dependency-free checks and runs any subset over a single git ls-files read. - gnn_conformance.py owns pin validation (schema gnn-importer-pin/v1), the pinned-parser install, and the sketch/exemplar conformance that previously lived as two inline heredocs in ci.yml. - gate.py exposes the arms (links, python, notebooks, checkpoints, archive, tests, gnn, fast, full, timings), so a local run and a CI run execute the same command, and generates docs/gate-timings.md from measured runs. tests/test_gate.py covers link resolution and repository escape, Python compilation, notebook JSON and outputs, checkpoint detection, pin mutations, and asserts the workflow invokes the documented commands.
Each job now invokes one gate command: the docs job runs the fast arm and the conformance job runs the gnn arm with --install. Job keys and display names are unchanged. The duplicate pin parsing and literal repository/tag/revision assertions disappear from the workflow; the script validates the pin once.
- docs/RUN_GUIDE.md: the entry point, every arm with its command, the two CI job keys and display names, the gnn-importer-pin/v1 pin (v5.0.3, 8f293d9ba810e6eda5c09842d9c7ed9ffa5f92c1), the local venv recipe, and why the repository has no lint or type arm. - docs/documentation-index.md: the flat index of long-lived documentation the hub was missing. - docs/gate-timings.md: generated by gate.py timings, never hand-edited; the tests arm fails when it stops listing every measured arm. - docs/README.md and docs/index.md link the new pages; .github/README.md, .github/GNN.md, README.md, AGENTS.md, CONTRIBUTING.md, the literature-area README, and the .aii sidecar now name the single gate command. - TO-DO.md records the change.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changes
One gate entry point, arms you can run alone.
.github/scripts/gate.pyis now the only command line; the four archive checks moved intoarchive_checks.pyand the GNN job body moved out ofci.ymlintognn_conformance.py.check_archive.pyis gone (clean cutover: every reference updated in the same PR).linkspython .github/scripts/gate.py linkspythonpython .github/scripts/gate.py pythonnotebookspython .github/scripts/gate.py notebookscheckpointspython .github/scripts/gate.py checkpointsarchivepython .github/scripts/gate.py archivegit ls-filesreadtestspython .github/scripts/gate.py testsgnnpython .github/scripts/gate.py gnn --installfast(default)python .github/scripts/gate.py fastarchive+tests; CI docs jobfullpython .github/scripts/gate.py fullfast+gnntimingspython .github/scripts/gate.py timings --include-gnndocs/gate-timings.mdCI calls the same commands, and holds no check body. Job keys and display names are unchanged:
docs-and-scripts/docs and scriptsrunsgate.py fast;gnn-conformance/gnn conformance (pinned)runsgate.py gnn --install. The duplicated work is gone: the two inline heredocs each re-parsed.github/gnn-pin.jsonand re-asserted the repository/tag/revision literals on top of the pin file; the script now validates the pin once, against schemagnn-importer-pin/v1, and the workflow states no pin literals.Docs.
docs/RUN_GUIDE.md(arms, job keys/commands, pin, local venv recipe),docs/documentation-index.md(flat index the hub was missing),docs/gate-timings.md(generated, never hand-edited; thetestsarm fails if it stops listing every measured arm). Hub, flat index,.github/README.md,.github/GNN.md, root README/AGENTS/CONTRIBUTING, the literature-area README and the.aiisidecar all name the single command.TO-DO.mdrecords the change.Pin documented, not restated in prose:
.github/gnn-pin.json, schemagnn-importer-pin/v1,ActiveInferenceInstitute/Generalized_Notation_Notation, tagv5.0.3, revision8f293d9ba810e6eda5c09842d9c7ed9ffa5f92c1, recorded2026-11-12..github/GNN.mdrecords what the conformance arm parses (sketch parse + syntax validation + type check, falling back to the pinnedinput/gnn_files/basics/static_perception.mdexemplar; receipt reports"source": "pinned-exemplar").No lint or type arm, deliberately. The repository has no linter, type checker, package,
pyproject.toml, or lockfile; the archive checks are its only static analysis. Adding Ruff/mypy without a project to configure them for would report on scripts whose execution needs an uncommitted PDF corpus. Documented inRUN_GUIDE.md→ "Why no lint or type arm".Composite action: the workflow does not use
ActiveInferenceInstitute/.github/.github/actions/setup-python-uv@7159e67315330aac8e414aebae0ad1e999a41448. That action exists (fetched itsaction.ymlat the pinned SHA), but there is no uv project to sync here, so both jobs keepactions/setup-pythonpinned by commit at CPython 3.12.RUN_GUIDE.mdrecords this and the adoption point.Measured wall time (this host, one run each)
Archive arm, CPython 3.15.2 / 3.12.16, Darwin arm64:
check_archive.py→gate.py archive)tests(new)fast= archive + tests (what CI's docs job runs)links/python/notebooks/checkpointsaloneGNN job work, CPython 3.12.16, warm pip cache, measured twice because the first sample was noisy:
pip installdeps + inline heredoc install + inline heredoc verifypython .github/scripts/gate.py gnn --installgnnverify alone, parser pre-installed (gate.py gnn)No speedup claimed. The GNN arm's wall time is unchanged within noise (the work is pip + git clone + network); the archive arms cost ~40 ms more per invocation because each arm is its own process, and
fastadds 17 tests. What changed is composition: one implementation, one command per arm, the pin parsed and validated once instead of twice, and a CI workflow with no bodies to drift. Fresh per-arm numbers are indocs/gate-timings.md(generated).Verification (local; GitHub Actions is billing-locked org-wide, so these runs are the gate)
Negative control observed during the change: with
check_archive.pydeleted but docs still pointing at it,gate.py linksexited 1 with- .github/README.md: missing link target: scripts/check_archive.pyand- docs/README.md: missing link target: ../.github/scripts/check_archive.py— the links arm still catches the failure classdocs/README.mdrecords.Documentation check: the repository ships no mkdocs/Jekyll/markdown-link-check configuration (a static site was rejected in
TO-DO.md); its documentation check is thelinksarm, which is green over the 61 tracked files.manuscript/does not exist in this repository, so Goal C does not apply: there is no render command, no variables file, and no figure registry to bring to the template shape.