chore: address PR-86 review feedback (BEADS doc + template + CI-script compile gate)

Applies the actionable items from the PR-86 review:

- docs/BEADS.md: lead with a one-sentence "what Beads is" + upstream link;
  state the stance explicitly (optional/additive, recommended for agent-driven
  flows, GitHub remains authoritative); add a YAML example block under
  Recommended Bead fields; replace the duplicated Closure checklist with a
  Bead-specific narrowing that cites the PR template + CONTRIBUTING; call out
  that .beads/ is wiped by git clean -fdx.
- .github/pull_request_template.md: collapse the "Local Beads" section into
  an HTML-commented opt-in block so it is invisible in the rendered preview
  until a Beads-using team uncomments it.
- CONTRIBUTING.md: document the one-shot git renormalisation step for
  Windows clones after the .gitattributes change lands.
- tests/test_scripts_compile.py: regression gate that py_compiles every
  .github/scripts/*.py. The "scripts unparseable" review finding was based on
  an older local Python — PEP 758 (3.14) makes the unparenthesised except
  clauses valid, so the scripts ARE fine on the project pin. The test
  guards against an actual syntax error landing in future.

Author: constk

.github/pull_request_template.md

@@ -40,9 +40,13 @@
 <!-- Required for UI change. Delete this section for non-UI PRs. -->
 
 
+<!--
 ## 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. -->
+Optional opt-in. Only add this section if your team uses a local Beads queue
+(see docs/BEADS.md). Uncomment the heading and replace this comment with the
+Bead id. GitHub issue linkage below is still required either way.
+-->
 
 
 ## Linked issue

CONTRIBUTING.md

@@ -56,6 +56,21 @@ gh pr merge <N> --admin --squash --delete-branch
 
 When a second collaborator joins, drop the `--admin` flag and adopt standard PR review. Update this section + `CODEOWNERS` in the same PR.
 
+## Line endings (Windows clones)
+
+This repo enforces LF line endings via `.gitattributes` (`* text=auto eol=lf`)
+and the pre-commit hygiene hook. If you cloned on Windows with
+`core.autocrlf=true`, the first checkout after pulling the `.gitattributes`
+change can leave the working tree out of sync with the index. Renormalise
+once:
+
+```sh
+git add --renormalize .
+git commit -m "chore: renormalise line endings"
+```
+
+After that, day-to-day work is unaffected.
+
 ## Local pre-push gate
 
 ```sh

docs/BEADS.md

@@ -1,11 +1,20 @@
 # Optional Beads execution queue
 
-Beads can be layered onto this harness as a local execution queue for teams that
-want dependency-aware task planning, agent handoffs, or ready/blocked views while
-still keeping GitHub Issues as the external source of truth.
-
-This document is intentionally conservative: it adds Beads guidance without
-replacing the repository's existing GitHub issue and PR process.
+[Beads](https://github.com/steveyegge/beads) is an open-source
+dependency-aware issue tracker designed for AI coding agents — it gives an
+agent a local ready/blocked view of work, a dependency graph, and restart-safe
+task claims that GitHub Issues alone do not.
+
+This document is **optional and additive**. The base harness does not assume
+Beads; if your team has no agent or multi-actor execution concern, GitHub
+Issues plus the PR template is sufficient and you can skip this doc entirely.
+Beads is recommended specifically when you are coordinating an LLM agent (or
+several) against this repo and want dependency planning the public issue
+tracker does not provide. The README and `docs/HARNESS.md` references describe
+Beads as optional infrastructure, not part of the standard contributor flow.
+
+Wherever Beads is used, GitHub Issues remain the external source of truth and
+the authority for issue closure.
 
 ## Review of existing GitHub issue guidance
 
@@ -78,8 +87,26 @@ without reopening every browser tab:
 | `evidence` | Paths or URLs for test output, review notes, screenshots, or deploy checks. |
 | `closeout` | Merge SHA, PR URL, and verification notes once complete. |
 
+A short YAML example:
+
+```yaml
+external_ref: https://github.com/owner/repo/issues/123
+github_issue: 123
+acceptance: |
+  /api/v1/echo rejects payloads >1KiB with HTTP 413.
+dependencies: [122]   # other Bead ids or GitHub issues
+status: ready
+owner: agent-a
+evidence:
+  - tests/test_api.py::test_echo_size_cap
+closeout: null
+```
+
 Avoid storing secrets, tokens, credentials, private customer data, or raw
 production payloads in Beads. Treat Beads data as local operational metadata.
+Note that `.beads/` is gitignored, so anything Beads stores locally — including
+agent-action audit logs — is wiped by `git clean -fdx`; commit deliberate
+summaries to the repo if you need them to survive workspace resets.
 
 ## PR discipline when Beads are used
 
@@ -107,15 +134,16 @@ are explicit.
 
 ## Closure checklist
 
-Before marking a Bead done:
+The PR-merge and issue-closure gates already live in
+`.github/pull_request_template.md` and `CONTRIBUTING.md` — don't duplicate them
+here. The Bead-specific closure rule is narrower:
 
-- The GitHub issue is still the correct external requirement.
-- The PR links the GitHub issue and, where useful, the Bead id.
-- Required CI checks passed or have documented non-applicability.
-- Required review happened according to repository policy.
-- Any requested browser, deploy, eval, or security evidence is attached or
-  linked.
-- The GitHub issue receives a closeout note before or during closure.
+- Do not mark a Bead done until the GitHub issue's closure conditions (per the
+  PR template and `CONTRIBUTING.md`) are met. Beads track the local execution
+  state of work GitHub already authorised; they don't grant new closure
+  authority.
+- If the Bead and the GitHub issue disagree on scope, acceptance, or status,
+  stop and reconcile against GitHub before continuing.
 
 Beads improve local throughput only if they reduce ambiguity. If a Bead and a
-GitHub issue disagree, stop and reconcile them before implementation continues.
+GitHub issue disagree, the GitHub issue wins.

tests/test_scripts_compile.py

@@ -0,0 +1,28 @@
+"""Every script in `.github/scripts/` must parse on the project's pinned Python.
+
+Catches a class of regression where a script lands with a syntax error that
+the corresponding CI gate happens to not exercise. Cheap and broad: one test,
+one `py_compile.compile` per script.
+"""
+
+from __future__ import annotations
+
+import py_compile
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SCRIPTS_DIR = REPO_ROOT / ".github" / "scripts"
+
+
+def _ci_scripts() -> list[Path]:
+    return sorted(p for p in SCRIPTS_DIR.glob("*.py") if p.is_file())
+
+
+@pytest.mark.parametrize("script", _ci_scripts(), ids=lambda p: p.name)
+def test_ci_script_compiles(script: Path) -> None:
+    try:
+        py_compile.compile(str(script), doraise=True)
+    except py_compile.PyCompileError as exc:  # pragma: no cover — failure path
+        pytest.fail(f"{script.name} failed to compile: {exc.msg}")