chore: add optional Beads issue queue guidance

Author: jakelindsay87

.gitattributes

@@ -0,0 +1,11 @@
+# The pre-commit hook stack enforces LF line endings. Keep checkout behavior
+# aligned across Windows, macOS, and Linux so `pre-commit run --all-files` does
+# not rewrite the working tree on Windows clones with global autocrlf enabled.
+* text=auto eol=lf
+
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary

.github/pull_request_template.md

@@ -40,6 +40,11 @@
 <!-- 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. -->
+
+
 ## Linked issue
 
 Closes #

.github/scripts/check_aspirational_tickets.py

@@ -57,6 +57,7 @@
 from pathlib import Path
 
 INVARIANTS_DOC = Path("docs/INVARIANTS.md")
+GITHUB_API_ERRORS = (urllib.error.URLError, TimeoutError, json.JSONDecodeError)
 
 # A marker line *starts* with one or two asterisks immediately followed by
 # `Aspirational` and a word boundary. Avoids picking up mid-sentence prose
@@ -88,7 +89,7 @@ def _issue_state(repo: str, number: str, token: str) -> str | None:
     try:
         with urllib.request.urlopen(req, timeout=5) as response:  # noqa: S310
             payload = json.loads(response.read().decode("utf-8"))
-    except urllib.error.URLError, TimeoutError, json.JSONDecodeError:
+    except GITHUB_API_ERRORS:
         return None
     state = payload.get("state")
     return state if isinstance(state, str) else None

.github/scripts/check_pin_freshness.py

@@ -84,6 +84,7 @@ def _load_pin_module() -> ModuleType:
 
 _pins = _load_pin_module()
 _API_BASE = "https://api.github.com"
+GITHUB_API_ERRORS = (urllib.error.URLError, TimeoutError, json.JSONDecodeError)
 
 
 def _fetch_json(url: str, token: str) -> dict[str, object] | None:
@@ -104,7 +105,7 @@ def _fetch_json(url: str, token: str) -> dict[str, object] | None:
     try:
         with urllib.request.urlopen(req, timeout=10) as response:  # noqa: S310
             payload = json.loads(response.read().decode("utf-8"))
-    except urllib.error.URLError, TimeoutError, json.JSONDecodeError:
+    except GITHUB_API_ERRORS:
         return None
     return payload if isinstance(payload, dict) else None
 

.github/scripts/check_tests_present.py

@@ -43,6 +43,8 @@
 import sys
 from pathlib import Path
 
+EVENT_READ_ERRORS = (OSError, json.JSONDecodeError)
+
 # Prefixes that declare a behaviour change → tests required.
 BLOCKING_PREFIXES: frozenset[str] = frozenset({"feat", "fix"})
 
@@ -59,7 +61,7 @@ def pr_title_from_event() -> str | None:
         return None
     try:
         data = json.loads(Path(event_path).read_text(encoding="utf-8"))
-    except OSError, json.JSONDecodeError:
+    except EVENT_READ_ERRORS:
         return None
     pr = data.get("pull_request")
     if not isinstance(pr, dict):

.github/scripts/check_version_bump.py

@@ -39,6 +39,7 @@
 PYPROJECT = Path("pyproject.toml")
 UV_LOCK = Path("uv.lock")
 PACKAGE_NAME = "harness-python-react"
+EVENT_READ_ERRORS = (OSError, json.JSONDecodeError)
 
 # Match the project's self-version block in uv.lock:
 #
@@ -105,7 +106,7 @@ def pr_title_from_event() -> str | None:
         return None
     try:
         data = json.loads(Path(event_path).read_text(encoding="utf-8"))
-    except OSError, json.JSONDecodeError:
+    except EVENT_READ_ERRORS:
         return None
     pr = data.get("pull_request")
     if not isinstance(pr, dict):

.gitignore

@@ -3,6 +3,10 @@
 .claude/bash-log.txt
 .claude/worktrees/
 
+# Optional local Beads queue state
+.beads/
+beads/
+
 # Node / Frontend
 node_modules/
 frontend/dist/

CONTRIBUTING.md

@@ -34,14 +34,15 @@ The subject is **lowercase** after the colon. Title Case prose (`Add the thing`)
 
 1. Open the issue first. Use a feature/bug template; fill every section.
 2. Branch off `develop` with the matching name.
-3. Land one logical change per PR. Stack PRs if the work is naturally split.
-4. The PR template asks five things — answer each (`None` is valid where applicable):
+3. If your team uses Beads, mirror or claim the linked issue in the local Beads queue after the issue exists. Beads track local ready/blocked execution only; GitHub Issues remain canonical for scope, discussion, PR linkage, and closure.
+4. Land one logical change per PR. Stack PRs if the work is naturally split.
+5. The PR template asks five things — answer each (`None` is valid where applicable):
    - **What & why** (1–3 lines)
    - **Test plan** (checkbox list; CI covers most of it)
    - **Invariants affected** — cite numbered rules from `docs/INVARIANTS.md`
    - **New deps / actions / external surface** (anchor for supply-chain review)
    - **Screenshots** (UI changes only)
-5. Wait for green CI + a code-owner review before merging.
+6. Wait for green CI + a code-owner review before merging.
 
 ### Solo-owner merge policy
 

README.md

@@ -15,9 +15,10 @@
 - **Backend:** Python 3.14, FastAPI, Pydantic v2 (`StrictModel` base), `uv` deps, OpenTelemetry SDK + OTLP exporter, structured JSON logs, generic tool-registry pattern.
 - **Frontend:** Node 24 LTS, React 19.2, Vite 8, TypeScript strict, ESLint 10 flat config, Prettier, Vitest + jsdom + Testing Library.
 - **Eval harness:** provider-agnostic runner + LLM-judge `Protocol`, three tolerance modes (exact / numeric / semantic), one example golden case, nightly workflow (disabled by default).
-- **CI:** 15 required status checks across `ci.yml` (lint/format, mypy strict, unit tests, coverage ≥75%, import-linter architecture, pre-commit, frontend build, frontend quality, branch-protection sync, commit-type sync) + `security.yml` (gitleaks, pip-audit, npm audit, trivy) + PR-title lint.
+- **CI:** 21 required status checks across `ci.yml` (lint/format, mypy strict, unit tests, coverage, import-linter architecture, pre-commit, frontend build, frontend quality, branch-protection sync, commit-type sync, version/action/tests/docs audits) + `security.yml` (gitleaks, pip-audit, npm audit, trivy) + PR-title lint.
 - **Release:** tag-triggered workflow that builds the image, pushes to `ghcr.io`, generates a CycloneDX SBOM, and publishes the GitHub Release.
 - **Agent integration:** `.claude/hooks/` (forbidden-flag blocker, secret scan, formatter dispatch, SessionStart context) + six auto-activating skills (architect / code-reviewer / devops / frontend / qa-engineer / technical-writer).
+- **Issue execution:** GitHub Issues remain the external source of truth; optional Beads guidance adds a local dependency-aware execution queue without changing issue closure authority.
 - **Docker:** multi-stage Dockerfile (non-root, healthcheck), `docker compose up` boots app + frontend + Jaeger.
 
 ## Quickstart
@@ -114,6 +115,7 @@ See [`docs/HARNESS.md`](docs/HARNESS.md) for the full umbrella. Highlights:
 | [`docs/BOUNDARIES.md`](docs/BOUNDARIES.md) | Module layering + the import-linter contracts |
 | [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) | Local setup, branching, justfile, CI |
 | [`docs/EVAL_HARNESS.md`](docs/EVAL_HARNESS.md) | Eval flywheel + opt-in for the nightly workflow |
+| [`docs/BEADS.md`](docs/BEADS.md) | Optional local Beads queue layered under GitHub Issues |
 | [`docs/SECURITY.md`](docs/SECURITY.md) | Threat model + defence-in-depth map |
 | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Scaffold-level component view |
 | [`CONTRIBUTING.md`](CONTRIBUTING.md) | Branching, commit format, PR flow |

docs/BEADS.md

@@ -0,0 +1,121 @@
+# 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.
+
+## Review of existing GitHub issue guidance
+
+The current harness already treats GitHub as the public planning and merge
+record:
+
+- `.github/ISSUE_TEMPLATE/bug.md`, `feature.md`, and `eval-regression.md`
+  define the supported intake paths, and blank issues are disabled in
+  `.github/ISSUE_TEMPLATE/config.yml`.
+- `CONTRIBUTING.md` requires one issue per branch, short-lived branches named
+  `<type>/<issue-number>-<kebab-title>`, and green CI plus review before merge.
+- `.github/pull_request_template.md` requires What & why, Test plan,
+  Invariants affected, supply-chain surface, Screenshots when relevant, and a
+  linked issue.
+- `CLAUDE.md` and `docs/DEVELOPMENT.md` describe the same one-issue,
+  one-branch, `develop` to `main` release flow for agent and human operators.
+- `docs/TASKS.md` is a project-local planning map cross-referenced with GitHub
+  issues and the project board.
+
+There is no Beads-specific policy in the base harness today. Any Beads addition
+must therefore be additive and must not make GitHub issue state ambiguous.
+
+## GitHub Issues vs Beads
+
+| System | Owns | Does not own |
+|---|---|---|
+| GitHub Issues | Public backlog, user-facing requirements, labels, project board state, discussion, acceptance criteria, links from PRs, and final issue closure. | Local agent claims, transient execution notes, or dependency scheduling that would be noisy in the public issue. |
+| Beads | Local execution queue, ready/blocked views, dependency graph, implementation notes, reviewer handoff notes, and restart-safe task claims. | The canonical requirement, public status, release notes, or authority to close a GitHub issue. |
+
+The rule is simple: **GitHub answers what work exists and whether it is
+externally done; Beads answers what the local execution system should pick up
+next.**
+
+## Sync contract
+
+When using Beads with this harness:
+
+1. Create or confirm the GitHub issue first.
+2. Mirror the issue into Beads with an immutable external reference:
+   - GitHub repository owner/name.
+   - GitHub issue number.
+   - GitHub issue URL.
+   - Original issue title.
+3. Use Beads for local status only: `ready`, `in_progress`, `blocked`,
+   `review`, or `done` are execution states, not replacements for the GitHub
+   issue state.
+4. Put the Bead id in local notes, branch notes, or PR body when useful, but
+   keep `Closes #<issue>` pointing at the GitHub issue.
+5. Do not close a GitHub issue because a Bead is marked done. Close only after
+   the PR is merged, required checks are green, any required manual or browser
+   validation is recorded, and a human-readable note has been added to the
+   issue or PR.
+
+If the GitHub issue changes after import, update the Bead from GitHub before
+continuing. GitHub wins on scope, acceptance criteria, and user-visible status.
+
+## Recommended Bead fields
+
+A Bead should carry enough information for a new agent or contributor to resume
+without reopening every browser tab:
+
+| Field | Purpose |
+|---|---|
+| `external_ref` | GitHub issue URL, for example `https://github.com/owner/repo/issues/123`. |
+| `github_issue` | Numeric issue id used by branches and PRs. |
+| `acceptance` | The current acceptance criteria copied or summarized from GitHub. |
+| `dependencies` | Other Beads or GitHub issues that must land first. |
+| `status` | Local execution state. |
+| `owner` | Optional local agent or human claim. |
+| `evidence` | Paths or URLs for test output, review notes, screenshots, or deploy checks. |
+| `closeout` | Merge SHA, PR URL, and verification notes once complete. |
+
+Avoid storing secrets, tokens, credentials, private customer data, or raw
+production payloads in Beads. Treat Beads data as local operational metadata.
+
+## PR discipline when Beads are used
+
+The existing PR template still applies. Add Beads information without deleting
+any required section:
+
+- `Linked issue` remains `Closes #<issue>`.
+- Mention the Bead id or local queue reference under `What & why` or the
+  optional Beads section.
+- Include Beads-derived evidence paths in `Test plan` only when they are useful
+  to a reviewer.
+- If the Bead changed scope, update the GitHub issue before asking for review.
+- If the Bead was blocked by an external dependency, note that in the PR or
+  issue rather than hiding it in the local queue.
+
+## Local artifact hygiene
+
+Beads state is usually local execution metadata. Do not commit raw Beads
+databases, scratch exports, or agent logs by default. Commit only intentional
+summaries or docs that reviewers need.
+
+If a downstream project decides to version Beads state, document that policy in
+that project and make sure secret scanning, review, and retention expectations
+are explicit.
+
+## Closure checklist
+
+Before marking a Bead done:
+
+- 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.
+
+Beads improve local throughput only if they reduce ambiguity. If a Bead and a
+GitHub issue disagree, stop and reconcile them before implementation continues.