Skip to content
Merged
Show file tree
Hide file tree
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
15 changes: 9 additions & 6 deletions .github/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,15 @@
# CI guidance

The workflow installs `uv.lock`, then calls the arms of
`scripts/release_check.py` instead of repeating commands. The `test` matrix job
runs `--arm test-full`; the `gate` job runs lint, types, docs, manuscript,
smoke, and package once on 3.12; the `gnn-conformance` job provisions a Python
3.12 runtime from the GNN revision pinned in `specs/gnn-pin.json` and runs
`--arm gnn`. It is a required check and must not be converted into a skip when
the runtime cannot be provisioned.
`scripts/release_check.py` instead of repeating commands. The `test` matrix
contains only Python 3.11 and runs `--arm test-full`. The `gnn-conformance` job
(display name `gnn conformance (pinned)`) runs `--arm all`
on Python 3.12 with `GNN_RUNTIME_PYTHON` set to the separate runtime provisioned from `specs/gnn-pin.json`.
There is no separate `gate` job. Pinned conformance always runs in the `gnn`
arm; missing runtime dependencies must fail, never skip. PDF rendering remains
an explicit local `--arm render` selection. The workflow uses pinned
`astral-sh/setup-uv` directly, not the Institute composite; see
[`../docs/gate.md`](../docs/gate.md) for the exact action and command map.

Manuscript figure bytes are written by the host toolchain, and `uv.lock`
resolves different matplotlib versions for different Python versions, so the
Expand Down
15 changes: 10 additions & 5 deletions .github/GNN.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,16 @@
(`8f293d9ba810e6eda5c09842d9c7ed9ffa5f92c1`) and records SHA-256 digests for
the five parser files under `src/gnn/`.

The job installs that commit into a separate runtime, then runs
`python scripts/validate_gnn_spec.py --gnn-runtime <runtime> --json` and checks
that the resolved `gnn.__version__` matches the pin tag. The validator verifies
the installed parser file digests, parses `specs/gridworld_3x3.gnn.md` with the
pinned `MarkdownGNNParser`, and compares the declared parameters and the `A`,
The job installs that commit into a separate Python 3.12 runtime, then invokes
the canonical release gate with `--arm all` and `GNN_RUNTIME_PYTHON` set to that runtime. Its `gnn`
arm always performs both the offline drift check and real pinned validation;
a missing runtime fails instead of skipping conformance. See
[`docs/gate.md`](../docs/gate.md) for the complete job and arm map, and
[`docs/gnn.md`](../docs/gnn.md) for standalone validation commands.

The validator checks that the resolved `gnn.__version__` matches the pin tag,
verifies the installed parser file digests, parses `specs/gridworld_3x3.gnn.md`
with the pinned `MarkdownGNNParser`, and compares the declared parameters and the `A`,
`B`, `C`, `D`, and `E` matrices against the runtime model built by
`blockference.gnn`; it also requires the pinned semantic validator, the
B-orientation check, and the consistency checker to report no errors or
Expand Down
42 changes: 20 additions & 22 deletions .github/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ Choose the shortest path for your goal:
| Read the generative-model specification | [`docs/gnn.md`](../docs/gnn.md) and [`specs/gridworld_3x3.gnn.md`](../specs/gridworld_3x3.gnn.md) |
| Explore executable examples | [`notebooks/README.md`](../notebooks/README.md) |
| Read the publication source | [`docs/manuscript/README.md`](../docs/manuscript/README.md) |
| Trace publication figures to their sources | [`docs/manuscript/figure-registry.json`](../docs/manuscript/figure-registry.json) |
| Contribute or report a bug | [`docs/contributing.md`](../docs/contributing.md) |
| Report a security issue | [`SECURITY.md`](../SECURITY.md) |

Expand Down Expand Up @@ -77,32 +78,29 @@ The GitHub Actions workflow runs on pushes and pull requests targeting
`main`, using the committed `uv.lock` on Python 3.11 and 3.12. CI calls the
arms of the canonical gate in [`scripts/release_check.py`](../scripts/release_check.py):

* the `test` matrix job runs `--arm test-full` (full suite, 90% coverage floor);
* the `gate` job runs `--arm lint --arm types --arm docs --arm manuscript
--arm smoke --arm package` once on Python 3.12;
* the `gnn-conformance` job runs `--arm gnn` with a runtime provisioned from
`specs/gnn-pin.json`.
* the `test` matrix contains only Python 3.11 and runs `--arm test-full`;
* the Python 3.12 `gnn-conformance` job (display name
`gnn conformance (pinned)`) runs `--arm all` with `GNN_RUNTIME_PYTHON` set to a
separate pinned runtime provisioned from `specs/gnn-pin.json`.

The arms cover Ruff linting, repository-wide Markdown link/anchor validation,
mypy, the test suite, notebook hygiene and execution, real pipeline and CLI
smoke checks, manuscript validation/build/render drift, and a wheel import
smoke. [`docs/gate.md`](../docs/gate.md) lists them and
smoke checks, manuscript validation/build drift, and a wheel import smoke.
The full test suite therefore runs on both Python versions without a separate
`gate` job. PDF rendering remains an explicit local `--arm render` selection.
[`docs/gate.md`](../docs/gate.md) defines the arms, runtime-aware local
commands, and exact pinned `astral-sh/setup-uv` action; this workflow does not
use the Institute setup composite.
[`docs/_generated/gate-metrics.md`](../docs/_generated/gate-metrics.md) holds
the measured numbers.

Run the release gate locally with:

```bash
uv run python scripts/release_check.py --arm all
```

The fast default (`uv run python scripts/release_check.py`) runs lint, types,
the fast test selection, and docs. A separate `gnn conformance (pinned)` job
(job key `gnn-conformance`) installs the GNN revision pinned in
`specs/gnn-pin.json` into its own Python 3.12 runtime and validates
`specs/gridworld_3x3.gnn.md` against the declared runtime model. The gate is
intentionally fail-closed: a required check is not converted into a skip when
an optional backend or generated artefact is unavailable. See
the measured numbers and the statuses of the one-run before/after receipts.
Those receipts are not a claimed speedup; the failed offline package baseline
cache miss remains a failure.

The no-argument fast default runs lint, types, the fast test selection, and
docs. The release gate's `gnn` arm always validates
`specs/gridworld_3x3.gnn.md` against the declared runtime model using the pinned
parser. The gate is intentionally fail-closed: a missing GNN runtime, required
backend, or generated artifact cannot turn a required check into a skip. See
[`docs/development.md`](../docs/development.md) for the development workflow
and [`docs/design-contract.md`](../docs/design-contract.md) for the project
scope and invariants.
Expand Down
20 changes: 18 additions & 2 deletions .github/workflows/README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,20 @@
# workflows

The workflow installs the locked environment, runs Ruff and pytest, and checks
the complete smoke artefact tree through the package CLI.
[`ci.yml`](ci.yml) installs the locked environment and calls the canonical
release gate in two jobs:

| Job key | Python | Selection |
| --- | --- | --- |
| `test` | matrix: 3.11 only | `--arm test-full` |
| `gnn-conformance` | 3.12 | `--arm all` with `GNN_RUNTIME_PYTHON` set to the provisioned runtime |

The second job retains the display name `gnn conformance (pinned)` and installs
the revision in [`../../specs/gnn-pin.json`](../../specs/gnn-pin.json) into a
separate runtime. The full suite runs on both Python versions; all other release
arms run with conformance on Python 3.12. Missing pinned-runtime validation
fails the gate. There is no separate `gate` job, and PDF rendering remains an
explicit local arm.

The workflow uses pinned `astral-sh/setup-uv` directly, not the Institute
composite. [`../../docs/gate.md`](../../docs/gate.md) is authoritative for the
exact action pin, gate commands, and measured-receipt workflow.
45 changes: 7 additions & 38 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ jobs:
strategy:
fail-fast: false
matrix:
python-version: ["3.11", "3.12"]
python-version: ["3.11"]

steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
Expand Down Expand Up @@ -52,36 +52,6 @@ jobs:
path: coverage.xml
if-no-files-found: ignore

gate:
timeout-minutes: 60
# Lint, types, docs, manuscript, smoke, and package work runs once; the
# test matrix above repeats only the suite across supported Python versions.
name: gate (lint, types, docs, manuscript, smoke, package)
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

- name: Install uv
# v10.3.3; setup-uv publishes no floating v10 major tag, so @v10 is unresolvable
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2
with:
version: "0.13.7"
enable-cache: true
cache-dependency-glob: "uv.lock"

- name: Set up Python 3.12
run: uv python install 3.12

- name: Install locked package and development dependencies
run: uv sync --locked --extra dev --python 3.12

- name: Run the release arms
run: >-
uv run python scripts/release_check.py
--arm lint --arm types --arm docs --arm manuscript
--arm smoke --arm package

gnn-conformance:
timeout-minutes: 120
# Validates the committed GNN specification with the parser pinned in
Expand All @@ -106,8 +76,8 @@ jobs:
- name: Set up Python 3.12
run: uv python install 3.12

- name: Install locked package without development extras
run: uv sync --locked --python 3.12
- name: Install locked package and development dependencies
run: uv sync --locked --extra dev --python 3.12

- name: Provision the pinned GNN parser runtime
id: runtime
Expand All @@ -123,8 +93,7 @@ jobs:
"generalized-notation-notation @ git+${REPO}@${COMMIT}"
echo "python=$RUNNER_TEMP/gnn-runtime/bin/python" >> "$GITHUB_OUTPUT"

- name: GNN conformance arm
run: >-
uv run python scripts/release_check.py
--arm gnn --gnn-runtime "${{ steps.runtime.outputs.python }}"
--require-gnn
- name: Release arms (including Python 3.12 full tests and GNN conformance)
env:
GNN_RUNTIME_PYTHON: ${{ steps.runtime.outputs.python }}
run: uv run python scripts/release_check.py --arm all
9 changes: 7 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,14 @@ artefacts, and fail-closed validation.
```bash
uv sync --locked --extra dev
uv run python scripts/release_check.py # fast arms (default)
uv run python scripts/release_check.py --arm all # release gate
uv run python scripts/release_check.py --arm all --gnn-runtime /path/to/gnn-runtime/bin/python
uv run blockference pipeline --config configs/smoke.yml --output-root output
```

The release gate requires a separate pinned GNN runtime; replace the example
interpreter path above with yours. [`docs/gate.md`](docs/gate.md) defines the
arms and CI mapping, and [`docs/gnn.md`](docs/gnn.md) explains runtime setup.

The CLI has three explicit commands:

```bash
Expand Down Expand Up @@ -109,7 +113,8 @@ The grid-world generative model is declared in
[Generalized Notation Notation](https://github.com/ActiveInferenceInstitute/Generalized_Notation_Notation)
(GNN). The document is generated from the implementation and validated against
the upstream parser pinned in [`specs/gnn-pin.json`](specs/gnn-pin.json)
(GNN v5.0.3, commit `8f293d9ba`): the validator reads the declared parameters
(schema `gnn-importer-pin/v1`, GNN v5.0.3, commit
`8f293d9ba810e6eda5c09842d9c7ed9ffa5f92c1`): the validator reads the declared parameters
back, builds the runtime model from them, and requires the declared matrices to
match exactly. See [`docs/gnn.md`](docs/gnn.md) for the commands and the
conformance contract.
Expand Down
32 changes: 23 additions & 9 deletions TODO.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# ActiveBlockference TODO

Owner: Active Inference Institute
Last reviewed: 2026-11-11
Last reviewed: 2026-11-12

This file records documentation findings from the 2026-08-02 DOCS-DEEP pass and
the 2026-11-11 completeness pass.
the 2026-11-11 completeness pass, plus the subsequent estate alignment.
Items are grouped by the size of the documentation change required:

* **Minor** — typo, broken link, stale path, or formatting correction.
Expand Down Expand Up @@ -46,6 +46,15 @@ Items are grouped by the size of the documentation change required:
the manuscript and package floor can no longer disagree. The
`python_version < '3.11'` `tomli` fallback in `requirements.txt` remains a
data-file pin, not a second supported floor.
- [x] Align the documentation hub and flat index with long-lived guides,
generated receipts, and the manuscript figure registry; keep measured
values in generated metrics rather than human-maintained prose.
- [x] Document the fail-closed GNN arm, the canonical full parser pin, the
Python 3.11 test-only/Python 3.12 full-gate CI mapping, and the directly
pinned uv setup action without claiming use of the Institute composite.
- [x] Document receipt imports, including the failed offline package baseline
cache miss, without claiming a speedup; distinguish the declared NumPy
range from the actual lockfile resolution.

## Major

Expand All @@ -55,13 +64,18 @@ an executable publication validator.

## Open / deferred

- The Python-version claim under **Medium** is open pending an owner decision on
which side to change. All 2026-08-02 docs-deep items remain complete.
No unresolved item remains from the listed documentation findings. The Python
floor reconciliation under **Medium** is complete, not deferred.

## Verification notes

The pass verified the documented single-agent and multi-agent Python examples,
the `docs/api.md` pipeline example, the tutorial snippets, `uv run ruff check
blockference tests scripts GRTs`, manuscript validation/build drift checks, and
the repository-wide relative Markdown links and anchors. Full release verification
remains the canonical `uv run python scripts/release_check.py --arm all` command.
The earlier completeness pass verified the documented single-agent and
multi-agent Python examples, the `docs/api.md` pipeline example, the tutorial
snippets, Ruff, manuscript validation/build drift checks, and repository-wide
relative Markdown links and anchors. These are historical verification notes,
not results from the estate alignment.

The estate documentation edits were reviewed by reasoning only; integrated
verification belongs to the canonical release selection in
[`docs/gate.md`](docs/gate.md), with a configured pinned GNN runtime. The
generated metrics and receipts record actual runs, including failures.
18 changes: 15 additions & 3 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ Start here if you are new to the repository:
Generated facts live under [`_generated/`](_generated/README.md). Measured gate
numbers are in [`_generated/gate-metrics.md`](_generated/gate-metrics.md); do
not copy those numbers into prose.
The receipts retain failed and non-equivalent workloads, including the offline
package baseline cache miss; they do not establish a speedup.

## Concepts and design

Expand All @@ -37,12 +39,22 @@ not copy those numbers into prose.
schema notes.
* [`../notebooks/README.md`](../notebooks/README.md) — executable notebook
examples.
* [`../scripts/README.md`](../scripts/README.md) — release and publication tools.
* [`../tests/README.md`](../tests/README.md) — test layout and gate coverage.
* [`../.github/workflows/README.md`](../.github/workflows/README.md) — workflow
entry point; [`gate.md`](gate.md) owns the exact two-job CI map.
* [`../SECURITY.md`](../SECURITY.md) — private security reporting.
* [`../TODO.md`](../TODO.md) — documentation completion record.
* [`../GRTs/README.md`](../GRTs/README.md) — optional local research orchestration.
* [`../.aii/README.md`](../.aii/README.md) — InstituteOS metadata sidecar.

## Publication source

* [`manuscript/`](manuscript/) — the ordered publication source, formal
definitions, numbered equations, figures, bibliography, and reproducible
build commands.
* [`manuscript/README.md`](manuscript/README.md) — ordered publication source,
formal definitions, numbered equations, bibliography, and build commands.
* [`manuscript/SYNTAX.md`](manuscript/SYNTAX.md) — publication syntax and variables.
* [`manuscript/figure-registry.json`](manuscript/figure-registry.json) — figure
sources and artifact mapping.

The software verdicts described throughout these documents certify software and
artefact integrity only; they do not establish empirical adequacy of a
Expand Down
21 changes: 15 additions & 6 deletions docs/_generated/README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,23 @@
# `docs/_generated/`

Generated documentation. Every file here is written by a named script and
checked by a gate arm; do not edit these files by hand.
Generated facts here are written by named scripts and checked by gate arms;
do not edit them by hand. This README explains the producers.

| File | Producer | Check |
| --- | --- | --- |
| [`gate-metrics.md`](gate-metrics.md) | `scripts/gate_metrics.py` from [`gate-timings.json`](gate-timings.json) and [`gate-baseline.json`](gate-baseline.json) | `scripts/release_check.py --arm docs` |
| [`gate-baseline.json`](gate-baseline.json) | `scripts/gate_metrics.py --record-baseline PATH` imports real pre-change gate receipts | `scripts/gate_metrics.py --check` |
| [`gate-timings.json`](gate-timings.json) | `scripts/gate_metrics.py --record-timings PATH` imports real current gate receipts | `scripts/gate_metrics.py --check` |
| [`manuscript-variables.json`](manuscript-variables.json) | `scripts/manuscript_variables.py` | `scripts/release_check.py --arm manuscript` |

`gate-timings.json` is a recorded receipt from one `--timings` run of the gate;
`gate-baseline.json` records the pre-change arm commands and their measured wall
times. Both are evidence for the measured numbers, not claims about another
host.
`release_check.py --timings PATH` records actual gate commands, statuses, and
elapsed times. Repeat `--record-baseline PATH` for disjoint pre-change selections;
`--record-timings PATH` imports one combined current receipt into the canonical
record before generating `gate-metrics.md`. See
[`../gate.md`](../gate.md) for the authoritative recording and import commands.

The before/after records are one-run, host-specific evidence, not a controlled
benchmark or a claimed speedup. The offline package baseline cache miss is a
failed measurement, not a successful comparison. Missing arms remain unrecorded;
failed and non-equivalent workloads keep their status and qualifications.
Measured values belong in generated metrics only.
Loading
Loading