Skip to content

Commit 502bdbd

Browse files
docs(specs): note Phase 2 blockers in living-docs regen automation (#62)
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 <noreply@anthropic.com>
1 parent 71f2a99 commit 502bdbd

1 file changed

Lines changed: 31 additions & 0 deletions

File tree

docs/specs/living-docs-regen-automation/decisions.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,37 @@ If they forget, CI tells them in the same PR run.
122122
## Phase outline (when this spec is approved)
123123

124124
- **Phase 1** — Inventory the exact regen commands and write `make regen-all`.
125+
**Status: shipped via #61.**
125126
- **Phase 2** — Add the CI job, gated on relevant paths; verify it fails
126127
intentionally on a stale-artifact PR before flipping it to required.
128+
**Status: blocked.** See "Phase 2 blockers" below.
127129
- **Phase 3** — README update; make the contract official.
130+
131+
## Phase 2 blockers (discovered 2026-05-23)
132+
133+
Phase 2 implementation attempt surfaced two foundational issues:
134+
135+
1. **attune-author regen vs. staleness check disagree on source_hash.**
136+
Running `attune-author regenerate` writes a new `source_hash` into the
137+
template frontmatter, but immediately running `attune-author regenerate
138+
--dry-run` (or `status`) still reports the same feature as stale. The
139+
loop never reaches a fixed point. Likely cause: regen hashes a
140+
budget-truncated source view (see `ground_truth.budget: dropped X to
141+
fit budget` log lines), while the staleness check hashes the full
142+
source set. Until this is fixed upstream, "fail-if-stale" has no
143+
meaningful signal — every PR would fail forever.
144+
145+
2. **Spec premise conflicts with CI policy.** This spec originally
146+
proposed `make regen-all` + `git diff --exit-code` in CI. That
147+
requires `ANTHROPIC_API_KEY` in CI for polish. But the existing
148+
workflow (`.github/workflows/tests.yml:38-46`) has an **explicit
149+
guard** that fails CI if `ANTHROPIC_API_KEY` is set in the default
150+
suite, to prevent non-`@live`-marked tests from leaking real API
151+
calls. The `--dry-run` workaround (no API needed) was the obvious
152+
alternative, but it's blocked by issue #1.
153+
154+
**Phase 2 stays parked until the upstream attune-author bug is fixed.**
155+
Tracking: a chip was filed to debug + fix attune-author's hash
156+
mismatch. Once that lands and attune-gui can pin a fixed release,
157+
Phase 2 design needs a small refresh — likely `--dry-run` as the CI
158+
signal (no API key needed, no policy conflict).

0 commit comments

Comments
 (0)