diff --git a/.github/workflows/echo-total-check.yml b/.github/workflows/echo-total-check.yml new file mode 100644 index 0000000..f3ffeee --- /dev/null +++ b/.github/workflows/echo-total-check.yml @@ -0,0 +1,25 @@ +name: Docs Rollup Check + +on: + pull_request: + +jobs: + echo-total-up-to-date: + name: echo-total.md is up-to-date + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Generate echo-total.md + run: | + chmod +x scripts/gen-echo-total.sh + ./scripts/gen-echo-total.sh + - name: Fail if echo-total.md changed + run: | + set -euo pipefail + if ! git diff --quiet -- docs/echo-total.md; then + echo "docs/echo-total.md is out of date. Run 'make echo-total' (or scripts/gen-echo-total.sh) and commit the result." >&2 + git --no-pager diff -- docs/echo-total.md || true + exit 1 + fi diff --git a/Makefile b/Makefile index 2032d53..11e5e7e 100644 --- a/Makefile +++ b/Makefile @@ -3,7 +3,7 @@ SHELL := /bin/bash # Default docs port; override with: make docs PORT=5180 PORT ?= 5173 -.PHONY: hooks docs docs-build docs-ci +.PHONY: hooks docs docs-build docs-ci echo-total hooks: @git config core.hooksPath .githooks @chmod +x .githooks/* 2>/dev/null || true @@ -38,3 +38,8 @@ docs-build: docs-ci: @echo "[docs] CI build (no npm install)" @npm run --silent docs:build + +# Generate docs/echo-total.md rollup +echo-total: + @chmod +x scripts/gen-echo-total.sh + @./scripts/gen-echo-total.sh diff --git a/README.md b/README.md index aece16b..6ff5bc9 100644 --- a/README.md +++ b/README.md @@ -165,6 +165,12 @@ There's a ton of other advanced reasons why it's cool, but that's nerd stuff. Le - Peek at [`docs/legacy-excavation.md`](docs/legacy-excavation.md) to see which ideas survived the archaeological roast. - Track active work in [`docs/execution-plan.md`](docs/execution-plan.md); update it every session. +### Docs + +- Dev server: `make docs` (opens browser; uses `PORT` env var, default 5173) +- Static build: `make docs-build` +- Single-file rollup: `make echo-total` (generates `docs/echo-total.md` from top‑level docs; commit the result if it changes) + --- ## Contributing diff --git a/docs/decision-log.md b/docs/decision-log.md index c0c29fc..a7427c4 100644 --- a/docs/decision-log.md +++ b/docs/decision-log.md @@ -30,6 +30,8 @@ The following entries use a heading + bullets format for richer context. | 2025-10-30 | Docs rollup | Add generator script and `docs/echo-total.md` rollup of all top‑level docs | Single-file reference for reviewers and readers; preserves source of truth in individual docs | Keep rollup refreshed via script when docs change | | 2025-10-30 | Docs rollup review (PR-05) | Add MUSL job intent comment (rmg-core only) and fix generator script to use portable newlines (`printf`/`echo`) | Clarify CI intent and ensure rollup emits correct formatting | Merged `main` into branch (no rebase/force) | | 2025-10-30 | Motion negative tests (PR-06) | Add tests documenting NaN/Infinity propagation and invalid payload size NoMatch in motion rule | Clarify expected behavior without changing runtime; improves determinism docs via tests | Tests-only; no runtime impact | +| 2025-10-30 | Docs rollup check (PR-07) | Add CI workflow to verify `docs/echo-total.md` is regenerated | Prevents drift between source docs and the rollup | Fails PR with guidance if rollup is stale | +| 2025-10-30 | Docs tooling (PR-08) | Add `make echo-total` target and README docs section for rollup | Makes rollup refresh one command; improves contributor experience | Small tooling quality-of-life | | 2025-10-28 | PR #7 merged | Reachability-only snapshot hashing; ports demo registers rule; guarded ports footprint; scheduler `finalize_tx()` clears `pending`; `PortKey` u30 mask; hooks+CI hardened (toolchain pin, rustdoc fixes). | Determinism + memory hygiene; remove test footguns; pass CI with stable toolchain while keeping rmg-core MSRV=1.68. | Queued follow-ups: #13 (Mat4 canonical zero + MulAssign), #14 (geom train), #15 (devcontainer). | | 2025-10-27 | MWMR reserve gate | Engine calls `scheduler.finalize_tx()` at commit; compact rule id used on execute path; per‑tx telemetry summary behind feature. | Enforce independence and clear active frontier deterministically; keep ordering stable with `(scope_hash, family_id)`. | Toolchain pinned to Rust 1.68; add design note for telemetry graph snapshot replay. | diff --git a/docs/echo-total.md b/docs/echo-total.md index 4a0310b..39e7d97 100644 --- a/docs/echo-total.md +++ b/docs/echo-total.md @@ -1,7 +1,5 @@ # Echo Total Documentation Rollup -Generated: 2025-10-30 19:58:59 UTC - > This file is generated by scripts/gen-echo-total.sh. Edit source docs under docs/, not this rollup. --- @@ -305,6 +303,24 @@ This is Codex’s working map for building Echo. Update it relentlessly—each s - Added `scripts/gen-echo-total.sh` to generate `docs/echo-total.md` by concatenating top‑level docs in a stable order (priority: docs-index, architecture outline, execution plan, decision log; then others alphabetically). The rollup carries file banners and a generated timestamp. +> 2025-10-30 — PR-05 review fixes + +- CI: In `ci.yml`, documented why the MUSL job tests only `rmg-core` (wasm/FFI intentional exclusions). +- Script portability: replaced echo with `printf` (and a plain `echo '---'`) to emit real newlines in `scripts/gen-echo-total.sh`; removed non-portable `\n` echo usage. +- Synced with `origin/main` via merge (no rebase/force). + +> 2025-10-30 — PR-06: Motion negative tests (opened) + +- Added tests in `rmg-core` covering NaN/Infinity propagation and invalid payload size returning `NoMatch`. Tests-only; documents expected behavior; no runtime changes. + +> 2025-10-30 — PR-07: echo-total rollup check (CI) + +- Added workflow `.github/workflows/echo-total-check.yml` that regenerates `docs/echo-total.md` and fails the PR if the file differs, prompting authors to update the rollup. Keeps the single-file doc in sync. + +> 2025-10-30 — PR-08: Makefile target + README note (docs tooling) + +- Added `make echo-total` target to run the rollup generator. README now documents `docs` commands and the rollup target. + > 2025-10-29 — Geom fat AABB midpoint sampling (merge-train) @@ -530,6 +546,10 @@ The following entries use a heading + bullets format for richer context. | 2025-10-30 | Proptest seed pinning | Add dev‑dep `proptest` and a pinned‑seed property test for motion rule (`proptest_seed_pinning.rs`) | Establish deterministic, reproducible property tests and document seed‑pinning pattern | Tests‑only; no runtime impact | | 2025-10-30 | CI matrix | Add musl tests job (rmg-core; x86_64-unknown-linux-musl) and a manual macOS workflow for local runs | Cover glibc + musl in CI while keeping macOS optional to control costs | Determinism coverage improves; CI footprint remains lean | | 2025-10-30 | Docs rollup | Add generator script and `docs/echo-total.md` rollup of all top‑level docs | Single-file reference for reviewers and readers; preserves source of truth in individual docs | Keep rollup refreshed via script when docs change | +| 2025-10-30 | Docs rollup review (PR-05) | Add MUSL job intent comment (rmg-core only) and fix generator script to use portable newlines (`printf`/`echo`) | Clarify CI intent and ensure rollup emits correct formatting | Merged `main` into branch (no rebase/force) | +| 2025-10-30 | Motion negative tests (PR-06) | Add tests documenting NaN/Infinity propagation and invalid payload size NoMatch in motion rule | Clarify expected behavior without changing runtime; improves determinism docs via tests | Tests-only; no runtime impact | +| 2025-10-30 | Docs rollup check (PR-07) | Add CI workflow to verify `docs/echo-total.md` is regenerated | Prevents drift between source docs and the rollup | Fails PR with guidance if rollup is stale | +| 2025-10-30 | Docs tooling (PR-08) | Add `make echo-total` target and README docs section for rollup | Makes rollup refresh one command; improves contributor experience | Small tooling quality-of-life | | 2025-10-28 | PR #7 merged | Reachability-only snapshot hashing; ports demo registers rule; guarded ports footprint; scheduler `finalize_tx()` clears `pending`; `PortKey` u30 mask; hooks+CI hardened (toolchain pin, rustdoc fixes). | Determinism + memory hygiene; remove test footguns; pass CI with stable toolchain while keeping rmg-core MSRV=1.68. | Queued follow-ups: #13 (Mat4 canonical zero + MulAssign), #14 (geom train), #15 (devcontainer). | | 2025-10-27 | MWMR reserve gate | Engine calls `scheduler.finalize_tx()` at commit; compact rule id used on execute path; per‑tx telemetry summary behind feature. | Enforce independence and clear active frontier deterministically; keep ordering stable with `(scope_hash, family_id)`. | Toolchain pinned to Rust 1.68; add design note for telemetry graph snapshot replay. | diff --git a/docs/execution-plan.md b/docs/execution-plan.md index ddd962e..08af170 100644 --- a/docs/execution-plan.md +++ b/docs/execution-plan.md @@ -86,6 +86,14 @@ This is Codex’s working map for building Echo. Update it relentlessly—each s - Added tests in `rmg-core` covering NaN/Infinity propagation and invalid payload size returning `NoMatch`. Tests-only; documents expected behavior; no runtime changes. +> 2025-10-30 — PR-07: echo-total rollup check (CI) + +- Added workflow `.github/workflows/echo-total-check.yml` that regenerates `docs/echo-total.md` and fails the PR if the file differs, prompting authors to update the rollup. Keeps the single-file doc in sync. + +> 2025-10-30 — PR-08: Makefile target + README note (docs tooling) + +- Added `make echo-total` target to run the rollup generator. README now documents `docs` commands and the rollup target. + > 2025-10-29 — Geom fat AABB midpoint sampling (merge-train) diff --git a/scripts/gen-echo-total.sh b/scripts/gen-echo-total.sh index c0bc859..716dcb0 100755 --- a/scripts/gen-echo-total.sh +++ b/scripts/gen-echo-total.sh @@ -1,6 +1,12 @@ #!/usr/bin/env bash set -euo pipefail +# Bash 4+ is required for associative arrays used in this script. +if [[ -z "${BASH_VERSINFO:-}" || ${BASH_VERSINFO[0]} -lt 4 ]]; then + echo "gen-echo-total.sh requires bash>=4 (macOS: brew install bash)" >&2 + exit 2 +fi + ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)" DOCS_DIR="$ROOT_DIR/docs" OUT_FILE="$DOCS_DIR/echo-total.md" @@ -16,7 +22,6 @@ declare -A seen { printf '# Echo Total Documentation Rollup\n\n' - printf 'Generated: %s\n\n' "$(date -u '+%Y-%m-%d %H:%M:%S UTC')" printf '> This file is generated by scripts/gen-echo-total.sh. Edit source docs under docs/, not this rollup.\n\n' echo '---' @@ -39,7 +44,7 @@ declare -A seen printf '\n\n# File: %s\n\n' "$base" cat "$f" printf '\n\n---\n' - done < <(find "$DOCS_DIR" -maxdepth 1 -type f -name "*.md" -print0 | sort -z) + done < <(find "$DOCS_DIR" -maxdepth 1 -type f -name "*.md" -print0 | LC_ALL=C sort -z) } > "$OUT_FILE" echo "Wrote $OUT_FILE"