From 4dd26b7f7a72081804459152216db30fbd7333d0 Mon Sep 17 00:00:00 2001 From: GeneAI Date: Sat, 23 May 2026 22:31:05 -0400 Subject: [PATCH] docs(specs): note Phase 2 blockers in living-docs regen automation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two foundational issues surfaced during Phase 2 implementation: 1. attune-author regen and dry-run disagree on source_hash — the loop never reaches a fixed point. 2. Spec premise (full regen in CI) conflicts with the existing ANTHROPIC_API_KEY-must-not-be-set CI guard. Phase 1 marked shipped. Phase 2 parked pending upstream fix. Co-Authored-By: Claude Opus 4.7 --- .../living-docs-regen-automation/decisions.md | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/specs/living-docs-regen-automation/decisions.md b/docs/specs/living-docs-regen-automation/decisions.md index 06f4308..32a8b2d 100644 --- a/docs/specs/living-docs-regen-automation/decisions.md +++ b/docs/specs/living-docs-regen-automation/decisions.md @@ -122,6 +122,37 @@ If they forget, CI tells them in the same PR run. ## Phase outline (when this spec is approved) - **Phase 1** — Inventory the exact regen commands and write `make regen-all`. + **Status: shipped via #61.** - **Phase 2** — Add the CI job, gated on relevant paths; verify it fails intentionally on a stale-artifact PR before flipping it to required. + **Status: blocked.** See "Phase 2 blockers" below. - **Phase 3** — README update; make the contract official. + +## Phase 2 blockers (discovered 2026-05-23) + +Phase 2 implementation attempt surfaced two foundational issues: + +1. **attune-author regen vs. staleness check disagree on source_hash.** + Running `attune-author regenerate` writes a new `source_hash` into the + template frontmatter, but immediately running `attune-author regenerate + --dry-run` (or `status`) still reports the same feature as stale. The + loop never reaches a fixed point. Likely cause: regen hashes a + budget-truncated source view (see `ground_truth.budget: dropped X to + fit budget` log lines), while the staleness check hashes the full + source set. Until this is fixed upstream, "fail-if-stale" has no + meaningful signal — every PR would fail forever. + +2. **Spec premise conflicts with CI policy.** This spec originally + proposed `make regen-all` + `git diff --exit-code` in CI. That + requires `ANTHROPIC_API_KEY` in CI for polish. But the existing + workflow (`.github/workflows/tests.yml:38-46`) has an **explicit + guard** that fails CI if `ANTHROPIC_API_KEY` is set in the default + suite, to prevent non-`@live`-marked tests from leaking real API + calls. The `--dry-run` workaround (no API needed) was the obvious + alternative, but it's blocked by issue #1. + +**Phase 2 stays parked until the upstream attune-author bug is fixed.** +Tracking: a chip was filed to debug + fix attune-author's hash +mismatch. Once that lands and attune-gui can pin a fixed release, +Phase 2 design needs a small refresh — likely `--dry-run` as the CI +signal (no API key needed, no policy conflict).