docs: record deep-review findings and completions in TODO and log

Author: docxology

REVIEW_LOG_2026-08-02.md

@@ -0,0 +1,74 @@
+# Documentation deep-review log — 2026-08-02
+
+## Scope
+
+Reviewed all tracked Markdown documentation (70 files), including the root
+README and contributor guidance, `docs/`, the ordered manuscript source,
+tutorials, package/config/test/notebook/GRTs README files, `.github/` guidance,
+and documentation-facing scripts/configuration. Cross-checked public API,
+configuration, CLI, pipeline, environment, persistence, visualization,
+notebook, and manuscript claims against the implementation.
+
+## Preflight
+
+- Branch: `main`
+- Remote default branch: `origin/main`
+- Starting HEAD: `1fad3dfb957224afd5e73aa639c377e5b46bd2e2`
+- Starting working tree: clean
+- `git fetch origin` completed; branch was already current, so no pull was
+  required.
+- Documentation inventory: 70 tracked Markdown files; `docs/` contains a
+  concept/API/pipeline/development set, tutorials, and an ordered manuscript.
+
+## Findings
+
+### Minor — 4 findings
+
+1. `tests/envs/README.md` and `tests/utils/README.md` linked five directory
+   levels upward for root files; those targets resolved outside the repository.
+2. `configs/AGENTS.md` named a nonexistent `tests/test_config.py`; configuration
+   tests are distributed across current `tests/test_*.py` modules.
+3. The `scripts/build_manuscript.py` module docstring named
+   `docs/_build/manuscript.md`, while the builder writes
+   `docs/_build/manuscript/manuscript.md`.
+4. The root README did not link its documentation index or license, despite
+   both being high-value entry points.
+
+### Medium — 4 findings
+
+1. The root README Python API example configured two agents with only
+   `initial_state`, which the current implementation intentionally rejects as
+   non-distinct multi-agent starts.
+2. `docs/README.md` was only a list and omitted the glossary, notebooks,
+   configuration, and explicit beginner entry path.
+3. The three tutorials were short fragments despite their local contract saying
+   each should be a runnable end-to-end story with prerequisites and next steps.
+4. `docs/contributing.md` instructed contributors to fill in a PR template, but
+   no PR template exists under `.github/`.
+
+### Major — 0 findings
+
+The repository already has a coherent documentation structure, local guidance,
+strict manuscript validation, and a release gate. No responsible major overhaul
+was warranted.
+
+## Implemented changes
+
+- Corrected all verified broken/stale references.
+- Corrected and executed the README multi-agent example.
+- Expanded the documentation index and root entry-point links.
+- Rewrote the tutorials around the current package API and CLI.
+- Aligned contribution guidance with the repository's actual GitHub files.
+- Replaced the TODO roadmap with severity sections, completed entries, and
+  explicit deferred items.
+
+## Validation performed
+
+- Executed the README API example after correction.
+- Executed the `docs/api.md` pipeline example.
+- Executed the tutorial Python examples and checked the pipeline CLI commands
+  against the current CLI definition.
+- Ran the repo-wide relative Markdown link/anchor audit: no remaining internal
+  link or anchor failures after fixes.
+- Ran `uv run ruff check blockference tests scripts GRTs`: passed.
+- The complete release gate is run after the final documentation commits.

TODO.md

@@ -1,96 +1,61 @@
 # ActiveBlockference TODO
 
 Owner: Active Inference Institute
-Status: all scoped roadmap items closed (release gate green on this interpreter)
-Last reviewed: 2026-08-01
-
-This file is the forward-looking execution source of truth. The prior
-hardening, release-contract, and refinement work is intentionally absent; an
-item belongs here only when implementation, tests, documentation, generated
-artifacts, or verification still remains.
-
-## Completed / Closed (completion pass of 2026-08-01)
-
-The following roadmap items were fully implemented in source, tests, docs,
-manuscript, and CI this pass, and are closed.
-
-### Cross-interpreter + clean-install release verification (P0)
-- [x] CI matrix already runs the canonical release gate on Python 3.10, 3.11,
-      and 3.12; added a mypy `--python-version 3.10` type-check step.
-- [x] Added deliberately interrupted / partial-tree and reused-run tests so
-      stale manifests, partial trees, and old validation reports can never
-      yield a passing release verdict.
-- [x] Clean wheel-install smoke (import + quick start without the optional
-      `pymdp` extra) is exercised by `scripts/release_check.py` and CI.
-
-### Atomic publication across all artefact types (P1)
-- [x] JSON, config, CSV, NPZ, per-step, manifest, and every render (PNG/GIF)
-      are now published atomically through a sibling temporary file + rename;
-      a leftover temp file fails validation as drift. `run.log` remains
-      append-only (a live log cannot be atomic, per the contract).
-- [x] Added interruption tests: a failed writer leaves the previous file and
-      cleans its temp; a partial tree and a stale temp file both fail closed.
-
-### `validate_run_outputs` stage split (P1)
-- [x] Split the monolith into focused public stage validators
-      (tree structure, artifact presence, config, trajectory, model, manifest,
-      policies, per-step, and config↔trajectory / config↔model agreement) with
-      `validate_run_outputs` as a thin fail-closed aggregator.
-
-### Normalized typed trajectory schema (P1)
-- [x] Added `blockference.io.parse_trajectory_records` returning typed,
-      deterministically ordered `TrajectoryRecord` values; backend (radCAD vs
-      cadCAD) parity and persistence round-trips now compare bytes-as-values.
-
-### Formalized step/update protocol + 3.10 type check (P1)
-- [x] Added `CoreAgentUpdate` required-keys TypedDict and `CORE_UPDATE_FIELDS` /
-      `validate_update_envelope`; all adapters emit the same ten-field envelope
-      and are validated fail-closed. Mypy now checks 3.10-compatible stubs in CI.
-
-### Grid index / transition optimization (P1)
-- [x] `ActiveGridference` uses a precomputed coordinate→index dict (O(1) lookup)
-      instead of repeated `list.index` scans, with a brute-force parity test
-      proving exact matrix and coordinate-index agreement.
-
-### Publication drift baseline gate (P1)
-- [x] `build_manuscript.py --check` now regenerates figures into a temp dir and
-      compares bytes against the committed figures (checkout-independent), in
-      addition to the manuscript-text diff in `release_check.py`.
-
-### Generic discrete-environment protocol (P2)
-- [x] Added the `blockference.envs.DiscreteEnvironment` runtime-checkable
-      protocol (state identity, observations, actions, collisions,
-      stochasticity, serialization); `GridWorld` conforms and adds lossless
-      `serialize()` / `load()`.
-
-### Scientific-adequacy claims kept out of the software verdict (P2)
-- [x] README, `docs/pipeline.md`, `docs/design-contract.md`, and the manuscript
-      now state explicitly that `ValidationReport.ok` / `PipelineResult.ok`
-      certify software and artefact integrity only, never empirical adequacy.
-
-### Multi-agent start correctness (Minor/Medium hardening)
-- [x] A multi-agent run without distinct `simulation.initial_states` now fails
-      fast with an explicit error instead of crashing inside a simulation
-      backend; README, `docs/api.md`, `docs/pipeline.md`, `docs/migration-v1.md`,
-      the manuscript, and the example configs were corrected.
-- [x] Added request timeout to the OpenAI GRTs provider (default 60 s).
-
-## Forward-looking (not started)
-
-- [ ] Nothing scoped. Future work (additional environments, stochastic
-      transitions, learned `A`/`B`/`C`, factored state spaces, larger policy
-      search, network-backed research, and any empirical scientific-adequacy
-      claim) must enter as its own validated contract with independent
-      provenance and sensitivity analyses, per the design contract.
-
-## Exit criteria (all currently met on this interpreter; CI confirms 3.10/3.11/3.12)
-
-- [x] The canonical release gate passes on all supported Python versions (CI).
-- [x] A clean wheel install runs the documented quick start without `pymdp` and
-      the optional adapter fails with its documented installation message.
-- [x] A fresh and an interrupted run both validate fail-closed, with exact
-      agreement among JSON, NPZ, CSV, summary, manifest, renders, and report.
-- [x] All tracked notebooks and the manuscript pass their mandatory gates;
-      optional renderers pass when present.
-- [x] `ValidationReport.ok` and `PipelineResult.ok` remain the only release
-      verdicts as future environments and research workflows are added.
+Last reviewed: 2026-08-02
+
+This file records documentation findings from the 2026-08-02 DOCS-DEEP pass.
+Items are grouped by the size of the documentation change required:
+
+* **Minor** — typo, broken link, stale path, or formatting correction.
+* **Medium** — stale section rewrite, documentation restructure, or missing guide.
+* **Major** — large documentation-system overhaul or cross-cutting refactor.
+
+## Minor
+
+- [x] Fix four broken repository-root links in `tests/envs/README.md` and
+      `tests/utils/README.md`. (commit: pending)
+- [x] Replace the nonexistent `tests/test_config.py` reference in
+      `configs/AGENTS.md` with the current test-file convention. (commit: pending)
+- [x] Correct the generated-manuscript path in the `scripts/build_manuscript.py`
+      module documentation. (commit: pending)
+- [x] Link the root README to the documentation index and MIT license.
+      (commit: pending)
+
+## Medium
+
+- [x] Correct the root README Python example so its two-agent configuration
+      supplies distinct `simulation.initial_states` and executes under the
+      current validation contract. (commit: pending)
+- [x] Expand `docs/README.md` into a usable documentation index covering
+      concepts, tutorials, development, configuration, notebooks, and the
+      manuscript source. (commit: pending)
+- [x] Rewrite the three tutorials as short runnable stories with prerequisites,
+      current API/CLI examples, assertions or validation steps, and next steps.
+      (commit: pending)
+- [x] Remove the nonexistent PR-template claim from `docs/contributing.md` and
+      describe the actual pull-request information expected. (commit: pending)
+
+## Major
+
+No major documentation-system overhaul was identified. The repository already
+has a coherent root/docs/manuscript structure, local contributor guidance, and
+an executable publication validator.
+
+## Open / deferred
+
+- [ ] Add automated Markdown link and anchor validation to CI. Deferred because
+      the repository currently has no Markdown tooling dependency or CI command;
+      the pass used a repo-wide audit script without introducing a heavyweight
+      documentation toolchain.
+- [ ] Add a dedicated `SECURITY.md` policy. Deferred because no security-reporting
+      channel or policy owner is defined in the repository metadata; adding one
+      would require an organization-level decision rather than inventing contact
+      details.
+
+## 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` command.