chore: add optional Beads issue queue guidance

[jakelindsay87]

What & why

[constk]

Code review

Verdict: Request changes. The Beads documentation itself is fine, but this PR silently includes a fix: for four broken CI scripts under a chore: title — and the brokenness exposes a meta-gate that's been reporting green while doing nothing. That deserves to be split out, called out, and protected with a regression test.

---

🚨 Critical: this PR silently fixes four unparseable CI scripts

The diff "refactors" four scripts in .github/scripts/:

-    except urllib.error.URLError, TimeoutError, json.JSONDecodeError:
+    except GITHUB_API_ERRORS:

That's not a refactor — it's a fix. The original is invalid Python 3. I verified by compiling the actual blobs from origin/main:

Script	Status on main
check_aspirational_tickets.py	SyntaxError: multiple exception types must be parenthesized (line 91)
check_pin_freshness.py	SyntaxError (line 107)
check_tests_present.py	SyntaxError (line 62)
check_version_bump.py	SyntaxError (line 108)

These four scripts cannot be parsed or executed by Python 3. Yet the corresponding gates ("Aspirational ticket cite", "Tests required", "Version bump check", and the freshness audit shipped via #83) have been reporting green on every PR — including PR #77 last week and this PR. That means one of:

1. The CI step swallows the SyntaxError and exits 0 (continue-on-error: true, || true, etc.).
2. The workflow imports the modules via a path that masks the error.
3. The gate has never actually executed on a real PR since these typos landed.

This is more important than the Beads docs. The harness's whole thesis (per CLAUDE.md) is "every layer catches a different failure class without anyone remembering to run it" — four meta-gates have been silently dead.

Asks:

1. Split the syntax fix into its own fix: PR with the right title (so it lands in the changelog under fixes, is independently revert-able, and gets visibility).
2. Add a regression test — the simplest form is tests/meta/test_scripts_compile.py that walks .github/scripts/*.py and py_compile.compiles each. Makes "this script doesn't import" impossible to ship again.
3. Audit the workflow YAML for continue-on-error, if: always(), and || true on these four gate steps. Whatever masked the error needs to be removed now; merging the script fix without removing the mask just resets the trap for next time.
4. Once fixed, retro-run the four gates against recent merged PRs (#72–#85) to find anything that should have been blocked.

I'd block on at least items 1–3 before merge.

---

Scope / commit-type mismatch

This chore: PR does four different things:

1. New docs (Beads).
2. PR template change (Beads section).
3. CI script syntax fix → that's a fix:, not a chore:.
4. Repo-wide line-ending policy via .gitattributes → cross-cutting, deserves its own PR + CONTRIBUTING note.

CONTRIBUTING.md step 4 requires "one logical change per PR." The "Commit-type sync" gate doesn't catch this because it checks the enum, not the content.

Suggestion: split into three PRs —

• fix: parenthesize except clauses in CI scripts (+ regression test)
• chore: enforce LF line endings via .gitattributes
• docs: add optional Beads queue guidance (this one keeps the version bump)

---

docs/BEADS.md

Generally well-structured. Specific notes:

• No reference to Beads upstream. The doc is titled "Beads" and mentions Beads ~30 times but never says what Beads is or where to find it. A reader who hasn't heard of it has no path forward. Add a one-sentence intro + an upstream link.
• "Recommended Bead fields" table lists eight fields with no example. A short YAML/JSON example block would do more for adoption than the table.
• "Closure checklist" duplicates ~70% of .github/pull_request_template.md and CONTRIBUTING.md. Cite those instead — duplication is a known drift source in this harness (see check_required_contexts.py philosophy).
• The doc never says when not to use Beads. It's labeled optional, but README and HARNESS.md additions read as if it's now part of the standard flow ("Issue execution: GitHub stays canonical; Beads can drive local ready/blocked work"). Pick a stance: truly optional (keep README/HARNESS.md neutral) or recommended (say so explicitly with a justification).
• Security guidance is good. Consider also calling out that .beads/ being gitignored means agent-action audit logs stored there are lost on git clean -fdx — worth a sentence on what to commit vs. not.

---

PR template change

+## Local Beads
+
+<!-- Optional. If this repo/project uses a local Beads queue, include the Bead id or "None". GitHub issue linkage below is still required. -->

Putting an optional section above ## Linked issue slightly weakens the template — every contributor reads past it to find the required field. Consider an HTML-commented opt-in block (mirror how Screenshots is handled), so it's invisible in the rendered preview unless someone deletes the comment markers.

---

.gitattributes

* text=auto eol=lf

Correct given the pre-commit hook enforces LF, but on a Windows clone with core.autocrlf=true this triggers a one-shot renormalization the first time anyone touches an unrelated file. Worth a paragraph in CONTRIBUTING.md:

If you cloned on Windows, run git add --renormalize . && git commit once after pulling this change.

Binary patterns are fine but minor: *.woff / *.woff2 / *.zip would be additions worth pre-empting if any are ever introduced. Not a blocker.

---

Version bump

0.2.9 → 0.2.10 — both pyproject.toml and uv.lock updated, "Version bump check" passes. ✅

Whether 0.2.10 is right for a docs-only chore: PR depends on whether this repo bumps every PR by convention or only on user-visible change. If the former, document it in docs/DEVELOPMENT.md; right now it's implicit.

---

README / docs accuracy ✅

• README "15 required status checks" → "21 required status checks" matches reality (verified via statusCheckRollup on PR #77 / #86).
• HARNESS.md drops the literal "15 contexts" claim — good, that string was a known drift hazard.
• HARNESS.md "Onboarding path" renumber (5 → 6 → 7 with BEADS.md inserted) is correct.
• CONTRIBUTING.md step renumber 1–5 → 1–6 is correct.

---

Test coverage

• No tests added.
• The script fix in particular has no regression test — the highest-priority test gap in this PR.
• A tests/meta/test_doc_links.py that resolves relative links in the new docs (and in HARNESS_PRIMER.md, which now references 8+ docs by relative path) would also be cheap and broadly useful.

---

Security / supply chain ✅

• No new dependencies, no new GitHub Actions, no new external surfaces.
• .beads/ ignored prevents accidental commit of Bead state metadata.
• docs/BEADS.md correctly warns against storing secrets in Bead metadata.

---

Summary of asks before merge

1. Must: Split the .github/scripts/ syntax fix into its own fix: PR.
2. Must: Add a regression test that compiles every script in .github/scripts/.
3. Must: Audit and remove whatever was masking the SyntaxError in CI for the four affected gates.
4. Should: Move .gitattributes to its own PR with a CONTRIBUTING note about renormalization on Windows.
5. Should: In docs/BEADS.md, add a one-sentence "Beads is …" intro with an upstream link, and decide whether Beads is "optional" or "recommended" — and align README / HARNESS.md to that stance.
6. Nice: Reword the new PR-template section as an HTML-commented opt-in block.

The Beads doc + version bump are fine to keep as-is once split.

[constk]

Re-review on 4df67bd

Retracting the critical-finding section from my prior review. I claimed the four .github/scripts/*.py files were unparseable Python 3 based on a local compile() check. That was wrong: Python 3.14 ships PEP 758, which makes the unparenthesised except A, B, C: syntax valid. The project pins Python 3.14, so the scripts always parsed in CI — my local Python was older. Apologies for the 15-day hold on the PR; that finding shouldn't have been a blocker.

The other items I raised were valid, and 4df67bd addresses them cleanly:

Item	Status
docs/BEADS.md — one-sentence "what Beads is" + upstream link	✅
docs/BEADS.md — explicit optional / recommended stance	✅
docs/BEADS.md — YAML example under "Recommended Bead fields"	✅
docs/BEADS.md — closure checklist narrowed to Bead-specific rule (no template duplication)	✅
docs/BEADS.md — .beads/ + git clean -fdx caveat	✅
.github/pull_request_template.md — HTML-commented opt-in block	✅
CONTRIBUTING.md — Windows line-endings + git add --renormalize . recipe	✅
tests/test_scripts_compile.py — parametrised py_compile.compile(..., doraise=True) over every .github/scripts/*.py	✅ — clean, IDs by filename, correctly scoped to the project's pinned Python

Items deliberately not addressed (your call, on the record here):

• .github/scripts/*.py not modified — correct given the PEP 758 retraction.
• .gitattributes and version bump kept inside this PR — out of scope to re-litigate.
• Not split into three PRs — your decision upfront.

Approving. Thanks for the patience with the regression-test addition — tests/test_scripts_compile.py is exactly the cheap broad gate that closes the "syntax error in a script the gate doesn't happen to exercise" failure class, and it'd have shortened this whole thread had it existed before.