hotfix(ci/docs): deterministic docs rollup check

.github/workflows/echo-total-check.yml

@@ -18,8 +18,30 @@ jobs:
       - name: Fail if echo-total.md changed
         run: |
           set -euo pipefail
-          if ! git diff --quiet -- docs/echo-total.md; then
+          tmp=$(mktemp -d)
+          # Save the committed rollup from HEAD and the just-regenerated one
+          git show HEAD:docs/echo-total.md > "$tmp/before.md" || true
+          cp docs/echo-total.md "$tmp/after.md"
+          # Normalize header-only legacy lines: remove only in the header region
+          # (from file start up to the first blank line) lines that match
+          #   ^\s*[Gg]enerated(\s*(:|at:|by:))?
+          # This avoids deleting arbitrary occurrences deeper in the document.
+          normalize_header() {
+            awk '
+              BEGIN { in_header=1 }
+              {
+                if (in_header) {
+                  if ($0 ~ /^[[:space:]]*$/) { in_header=0; print; next }
+                  if ($0 ~ /^[[:space:]]*[Gg]enerated([[:space:]]*(:|at:|by:|on:))?/) next; else print
+                } else { print }
+              }
+            ' "$1"
+          }
+          normalize_header "$tmp/before.md" > "$tmp/before.norm" || true
+          normalize_header "$tmp/after.md"  > "$tmp/after.norm"  || true
+          if ! diff -u "$tmp/before.norm" "$tmp/after.norm" >/dev/null; then
+            echo "::error file=docs/echo-total.md,line=1,col=1::docs/echo-total.md is out of date. Run 'make echo-total' (or scripts/gen-echo-total.sh) and commit the result." >&2
             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
+            diff -u "$tmp/before.norm" "$tmp/after.norm" || true
             exit 1
           fi

docs/decision-log.md

@@ -158,3 +158,14 @@ The following entries use a heading + bullets format for richer context.
 - Context: PR‑10 (README/CI/docs) accidentally included commit header tests in `snapshot.rs`, overlapping with PR‑09 (tests‑only).
 - Decision: Remove the test module from PR‑10 to keep it strictly docs/CI/tooling; keep all BLAKE3 commit header tests in PR‑09 (`echo/pr-09-blake3-header-tests`).
 - Consequence: Clear PR boundaries; no runtime behavior change in PR‑10.
+
+## 2025-11-02 — Hotfix: CI docs rollup determinism
+
+- Context: CI rollup job failed on branches where `scripts/gen-echo-total.sh` previously wrote a timestamp header, causing `git diff` to always differ.
+- Decision: Update `.github/workflows/echo-total-check.yml` to normalize out `Generated:` lines before diffing, making the check deterministic across old/new rollup formats.
+- Consequence: No more false failures; contributors still run `make echo-total` locally when docs change.
+
+## 2025-11-02 — Hotfix follow-up: tighter normalization + annotations
+
+- Decision: Limit normalization to the header region only and accept case/whitespace/legacy variants (`Generated:`, `generated at:`, `Generated by:`). Emit a GitHub Actions `::error` annotation targeting `docs/echo-total.md` when differences remain to improve diagnostics.
+- Consequence: Clearer CI failures; minimal, targeted normalization avoids masking content issues.

docs/echo-total.md

@@ -529,6 +529,13 @@ Populate with concrete tasks in priority order. When you start one, move it to 
 - When finishing a milestone, snapshot the diagrams and link them in the memorial for posterity.
 
 Remember: every entry here shrinks temporal drift between Codices. Leave breadcrumbs; keep Echo’s spine alive. 🌀
+> 2025-11-02 — Hotfix: deterministic rollup check (CI)
+
+- Made CI rollup check robust against legacy non-deterministic headers by normalizing out lines starting with `Generated:` before comparing. Current generator emits a stable header, but this guards older branches and avoids false negatives.
+
+> 2025-11-02 — Hotfix follow-up: tighter normalization + annotation
+
+- CI normalization now only removes `Generated` header lines in the top-of-file header block (from start to first blank line) and tolerates whitespace/case variants and legacy forms like `Generated:`, `generated at:`, `Generated by:`. Added a GitHub Actions annotation on failure to point directly at `docs/echo-total.md`.
 
 
 ---
@@ -697,6 +704,17 @@ The following entries use a heading + bullets format for richer context.
 - Decision: Remove the test module from PR‑10 to keep it strictly docs/CI/tooling; keep all BLAKE3 commit header tests in PR‑09 (`echo/pr-09-blake3-header-tests`).
 - Consequence: Clear PR boundaries; no runtime behavior change in PR‑10.
 
+## 2025-11-02 — Hotfix: CI docs rollup determinism
+
+- Context: CI rollup job failed on branches where `scripts/gen-echo-total.sh` previously wrote a timestamp header, causing `git diff` to always differ.
+- Decision: Update `.github/workflows/echo-total-check.yml` to normalize out `Generated:` lines before diffing, making the check deterministic across old/new rollup formats.
+- Consequence: No more false failures; contributors still run `make echo-total` locally when docs change.
+
+## 2025-11-02 — Hotfix follow-up: tighter normalization + annotations
+
+- Decision: Limit normalization to the header region only and accept case/whitespace/legacy variants (`Generated:`, `generated at:`, `Generated by:`). Emit a GitHub Actions `::error` annotation targeting `docs/echo-total.md` when differences remain to improve diagnostics.
+- Consequence: Clearer CI failures; minimal, targeted normalization avoids masking content issues.
+
 
 ---
 

docs/execution-plan.md

@@ -302,3 +302,10 @@ Populate with concrete tasks in priority order. When you start one, move it to 
 - When finishing a milestone, snapshot the diagrams and link them in the memorial for posterity.
 
 Remember: every entry here shrinks temporal drift between Codices. Leave breadcrumbs; keep Echo’s spine alive. 🌀
+> 2025-11-02 — Hotfix: deterministic rollup check (CI)
+
+- Made CI rollup check robust against legacy non-deterministic headers by normalizing out lines starting with `Generated:` before comparing. Current generator emits a stable header, but this guards older branches and avoids false negatives.
+
+> 2025-11-02 — Hotfix follow-up: tighter normalization + annotation
+
+- CI normalization now only removes `Generated` header lines in the top-of-file header block (from start to first blank line) and tolerates whitespace/case variants and legacy forms like `Generated:`, `generated at:`, `Generated by:`. Added a GitHub Actions annotation on failure to point directly at `docs/echo-total.md`.