Skip to content

gate: one entry point with arms, CI dedupe, and generated timings docs - #9

Merged
docxology merged 3 commits into
mainfrom
estate/gate-docs-render
Nov 12, 2026
Merged

docxology merged 3 commits into
mainfrom
estate/gate-docs-render

Conversation

@docxology

Copy link
Copy Markdown
Collaborator

What changes

One gate entry point, arms you can run alone. .github/scripts/gate.py is now the only command line; the four archive checks moved into archive_checks.py and the GNN job body moved out of ci.yml into gnn_conformance.py. check_archive.py is gone (clean cutover: every reference updated in the same PR).

Arm Command Notes
links python .github/scripts/gate.py links relative Markdown links/images
python python .github/scripts/gate.py python tracked Python compiles
notebooks python .github/scripts/gate.py notebooks output-free JSON
checkpoints python .github/scripts/gate.py checkpoints no tracked checkpoints
archive python .github/scripts/gate.py archive the four above over one git ls-files read
tests python .github/scripts/gate.py tests 17 gate unit tests
gnn python .github/scripts/gate.py gnn --install pinned parser conformance
fast (default) python .github/scripts/gate.py fast archive + tests; CI docs job
full python .github/scripts/gate.py full fast + gnn
timings python .github/scripts/gate.py timings --include-gnn regenerates docs/gate-timings.md

CI calls the same commands, and holds no check body. Job keys and display names are unchanged: docs-and-scripts / docs and scripts runs gate.py fast; gnn-conformance / gnn conformance (pinned) runs gate.py gnn --install. The duplicated work is gone: the two inline heredocs each re-parsed .github/gnn-pin.json and re-asserted the repository/tag/revision literals on top of the pin file; the script now validates the pin once, against schema gnn-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; the tests arm 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 .aii sidecar all name the single command. TO-DO.md records the change.

Pin documented, not restated in prose: .github/gnn-pin.json, schema gnn-importer-pin/v1, ActiveInferenceInstitute/Generalized_Notation_Notation, tag v5.0.3, revision 8f293d9ba810e6eda5c09842d9c7ed9ffa5f92c1, recorded 2026-11-12. .github/GNN.md records what the conformance arm parses (sketch parse + syntax validation + type check, falling back to the pinned input/gnn_files/basics/static_perception.md exemplar; 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 in RUN_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 its action.yml at the pinned SHA), but there is no uv project to sync here, so both jobs keep actions/setup-python pinned by commit at CPython 3.12. RUN_GUIDE.md records this and the adoption point.

Measured wall time (this host, one run each)

Archive arm, CPython 3.15.2 / 3.12.16, Darwin arm64:

Arm Before After
archive checks (monolith check_archive.py → gate.py archive) 0.14 s 0.18 s
tests (new) — 0.38 s
fast = archive + tests (what CI's docs job runs) 0.14 s 0.27 s
links / python / notebooks / checkpoints alone n/a (one command) 0.25 / 0.21 / 0.20 / 0.14 s

GNN job work, CPython 3.12.16, warm pip cache, measured twice because the first sample was noisy:

Sequence Trial 1 Trial 2
before: pip install deps + inline heredoc install + inline heredoc verify 14.81 s 12.55 s
after: python .github/scripts/gate.py gnn --install 13.59 s 13.09 s
gnn verify alone, parser pre-installed (gate.py gnn) — 0.95 s
venv creation (environment prep, unchanged by this PR) 9.99 s 9.50 s

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 fast adds 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 in docs/gate-timings.md (generated).

Verification (local; GitHub Actions is billing-locked org-wide, so these runs are the gate)

$ python .github/scripts/gate.py fast
archive: ok (61 tracked files; links resolve; Python compiles; notebooks are output-free JSON; no checkpoints)
Ran 17 tests in 0.008s
OK
tests: ok (17 tests)                                    # rc=0

$ ~/.cache/gnn-after/bin/python .github/scripts/gate.py gnn --install
{"gnn-version": "5.0.3", "models": 1, "pin-revision": "8f293d9ba810e6eda5c09842d9c7ed9ffa5f92c1", "result": "verified", "source": "pinned-exemplar"}   # rc=0

$ python .github/scripts/gate.py full
archive: ok (61 tracked files; ...); tests: ok (17 tests); gnn verified        # rc=0

$ python .github/scripts/gate.py --list        # 10 arms, no lint arm (documented)
$ python -c 'yaml.safe_load(open(".github/workflows/ci.yml"))'  # parses; jobs == docs-and-scripts, gnn-conformance; run steps == the two gate commands

Negative control observed during the change: with check_archive.py deleted but docs still pointing at it, gate.py links exited 1 with - .github/README.md: missing link target: scripts/check_archive.py and - docs/README.md: missing link target: ../.github/scripts/check_archive.py — the links arm still catches the failure class docs/README.md records.

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 the links arm, 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.

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.
@docxology
docxology merged commit 7ab2b6b into main Nov 12, 2026
0 of 4 checks passed
@docxology
docxology deleted the estate/gate-docs-render branch November 12, 2026 16:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant