Skip to content

AI Notes Index

docs/AI is for durable implementation notes: how a feature works, why a design choice was made, and what to check before changing it. Prefer updating an existing note over adding another one-off debugging log.

Architecture

  • joint-graph-architecture.md: current joint graph artifact flow.
  • public-markov-state-contract.md: public-state rules shared by WM, OM, exact graphs, and shielding.
  • opponent-model-joint-graph.md: OM assumptions over env_transition_graph.pkl.
  • opponent-model-training-semantics.md: root-state sample semantics for IOP training.
  • opponent-model-runtime-fastpath.md: legality-mask caching in OM rollouts.
  • world-model-checkpoint-loader.md: safe reloads for older world_model.pt checkpoints.

Shielding

  • budget-augmented-shielding.md: budgeted replacement-shield semantics.
  • shielding-overhaul.md: conservative value iteration and runtime wrapper.
  • shielded-notebook-integration.md: learned shield artifact flow in notebooks.
  • true-policy-exact-shield.md: exact true-policy shield baseline.
  • repeated-matrix-shield-feasibility.md: repeated matrix game repair pattern.
  • congestion-shield-infeasibility.md: Congestion detour repair details.
  • pursuit-3-agent-shield-infeasibility.md: why 3-agent Pursuit can fail reset feasibility under eventual-risk shielding.

Environments And Graphs

  • legal-dynamics-size.md: legal graph size accounting.
  • exact-graph-time-augmented-state-width.md: exact graph public-state width.
  • hidden-episode-cap-semantics.md: hidden truncation counters.
  • guard-exact-graph-memory.md: Guard exact graph memory guardrails.
  • gathering-exact-graph-freeze-timing.md: Gathering graph cache invalidation.
  • ice-duel-safe-start-dynamics.md: Ice Duel movement/shove dynamics.
  • pursuit-safety-label.md: Pursuit safety label semantics.

Notebooks And Exports

  • zensical-docs-site.md: user-facing Zensical docs site layout and update rules.
  • marimo-experiment-notebooks.md: experiment notebook conventions.
  • marimo-project-root-cwd.md: project-root cwd normalization.
  • notebook-environment-discovery.md: shared notebook environment metadata.
  • notebook-utils-layout.md: helper vs runnable notebook layout.
  • experiment-export-layout.md: history and figure export structure.
  • notebook-hyperparameter-pass-2026-04.md: April 2026 notebook defaults pass.
  • diagram-notebooks-expansion.md: common WM/OM/shielding diagram layer.
  • iop-diagram-notebooks.md: IOP level diagram notebook behavior.
  • iop-state-diagram-layout.md: IOP level diagram layout controls.

Training, Logging, And Visuals

  • jax-ippo-migration.md: current JAX trainer integration.
  • discrete-icpo-port.md: repo-native ICPO notes.
  • level0-holdout-metrics.md: level-0 OM validation metrics.
  • logging-engine.md: shared Loguru-backed logging adapter.
  • visualisation-styling.md: plotting style alignment.

Historical Debug Notes

These notes capture specific incidents or migrations. Keep them only while the failure mode is still useful for future debugging.

  • pursuit-3-agent-om-oom-debug.md
  • overview-documentation.md