From e5692c556d7aeecb842cb4d46b2ac3b8cb3758c3 Mon Sep 17 00:00:00 2001 From: ProjectUltra Agent Date: Thu, 30 Apr 2026 15:39:21 -0400 Subject: [PATCH] Agent task: 002-agent-pr-template --- .github/PULL_REQUEST_TEMPLATE.md | 90 ++++++++++++++++++++++++++++++++ docs/AGENTIC_DEVELOPMENT.md | 8 ++- 2 files changed, 97 insertions(+), 1 deletion(-) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..fc914b2 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,90 @@ + + +## Summary + + + +## Source + +- Task or backlog item: +- Related issues / PRs: + +## Risk Category + +Pick exactly one primary category. Add secondaries only if a reviewer must look at them too. + +- [ ] docs +- [ ] tooling (scripts, CI helpers, agent runner, repo config — no production source change) +- [ ] test-only (new/changed tests, fixtures, harnesses) +- [ ] PHY (waveform, DSP, sync, OFDM/PSK demod, CFO) +- [ ] ARQ (selective repeat, stop-and-wait, ACK/NACK, retransmission, file transfer) +- [ ] LDPC / FEC (encoder, decoder, interleaver, rate policy) +- [ ] audio (audio engine, device I/O, calibration paths) +- [ ] hardware (Mac/Pi rig scripts, calibration constants, lock behavior) +- [ ] security (permissions, secrets handling, network surface, agent allowlists) + +## Required Gates + +Run from the repo root. Paste the result for each gate that applies. + +- [ ] Local gate: `./agents/run_local_gate.sh` — result: +- [ ] Targeted CTest subset (if narrower than full ctest): `ctest --test-dir build -R '' --output-on-failure` — result: +- [ ] Coverage (Tier 0/Tier 1 source change): `./scripts/coverage_report.sh` — line / function / branch deltas vs baseline: +- [ ] Hardware smoke (PHY / ARQ / audio / hardware change): `SSH_KEY="$HOME/.ssh/id_pi5" ./agents/run_hardware_smoke.sh` — result + report dir, or `not required because ` +- [ ] CFO/sync/OFDM demod regression (if touched): `./tests/verify_cfo_chain.sh --cfo 50 --channel awgn --snr 20 --seed 42` — result: + +If a required gate is intentionally skipped, justify it on one line. "Not run" without a reason blocks merge. + +## Throughput / Robustness Evidence + +Required for any PHY / ARQ / LDPC / audio / waveform-policy change. Otherwise write `not applicable: `. + +| Profile (channel, SNR, rate, payload) | Command | Before (commit / metric) | After (commit / metric) | +|---|---|---|---| +| | | | | + +Report at minimum: frame/CW success, retransmission count, throughput (bps), and seed(s). Link to log paths under `/tmp/ultra_*` or `agents/reports/`. + +## Invariants & Calibration + +- [ ] No change to documented invariants in `docs/INVARIANTS.md`, or this PR updates that doc and `docs/CHANGELOG.md` with the rationale. +- [ ] No change to hardware calibration (mixer levels, `--inject-gain`, device names) unless the task explicitly asks for it. +- [ ] LDPC, ARQ, sync, and CFO feedback loops are not weakened. + +## Security & Privacy + +- [ ] No prompts, agent transcripts, or task-file copies committed. +- [ ] No `agents/reports/`, `agents/tmp/`, `/tmp/ultra_*`, or other run-time logs committed. +- [ ] No credentials, tokens, SSH keys, or `.env` material committed. +- [ ] No host-specific paths (e.g. `/Users/`, `pi5tester` IPs, private hostnames) hardcoded in source or tests. +- [ ] If permissions / allowlists / CI tokens changed, called out explicitly below: + + + +## Rollback + +- Revert plan: +- Data/state migrations to undo: + +## Residual Risks & Follow-ups + +- Risks accepted in this PR: +- Suggested follow-up tasks: + +--- + +## Automated Agent PR Checklist + +Fill this section only if the PR was produced by an agent runner (`agents/run_next_task.sh` / `watchdog.sh`). Humans authoring directly may delete it. + +- [ ] Task file path: +- [ ] Report directory: +- [ ] PR opened as **draft** (`AGENT_PR_DRAFT=1`). +- [ ] Branch is `agent/...`, not `main` and not a protected branch. +- [ ] CI status on this PR: +- [ ] Human reviewer required before marking ready-for-review and before merge. +- [ ] No commits authored outside the runner (`AGENT_ALLOW_AGENT_COMMITS` not set unless approved). diff --git a/docs/AGENTIC_DEVELOPMENT.md b/docs/AGENTIC_DEVELOPMENT.md index 6e6aaf6..7031885 100644 --- a/docs/AGENTIC_DEVELOPMENT.md +++ b/docs/AGENTIC_DEVELOPMENT.md @@ -134,6 +134,10 @@ human checks the diff, evidence, and CI result. `AGENT_TIMEOUT_SECONDS` requires `timeout(1)` on the agent host. Leave it unset on hosts without that command, or install GNU coreutils. +GitHub auto-loads `.github/PULL_REQUEST_TEMPLATE.md` into the PR body. Fill the +risk category, gates, evidence, security, and automated-agent sections from the +local-gate report and the task file before requesting review. + After that, install the macOS LaunchAgent example from `agents/launchd/`. Keep it in no-auto-commit mode until you have reviewed several successful worker branches. @@ -200,4 +204,6 @@ For PHY/ARQ changes, also run: SSH_KEY="$HOME/.ssh/id_pi5" ./agents/run_hardware_smoke.sh ``` -Merge only when the benchmark evidence matches the task goal. +Merge only when the benchmark evidence matches the task goal and the PR body +(filled from `.github/PULL_REQUEST_TEMPLATE.md`) shows the required gates, +risk category, evidence, and rollback notes.