PR-08: build/docs: make echo-total target + README note

.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

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

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

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. |
 

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. |
 

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)
 

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"