diff --git a/.github/workflows/echo-total-check.yml b/.github/workflows/echo-total-check.yml index f3ffeee..042d06b 100644 --- a/.github/workflows/echo-total-check.yml +++ b/.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 diff --git a/docs/decision-log.md b/docs/decision-log.md index 8866f1e..78c396f 100644 --- a/docs/decision-log.md +++ b/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. diff --git a/docs/echo-total.md b/docs/echo-total.md index 47b271d..fb564b4 100644 --- a/docs/echo-total.md +++ b/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. + --- diff --git a/docs/execution-plan.md b/docs/execution-plan.md index 1947e48..22b7eaa 100644 --- a/docs/execution-plan.md +++ b/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`.