[pid1]

What this changes

Upkeep and issue work now run in parallel, and the facts PR is written last from what they found. Before, one worker did upkeep, facts and issues in turn. When upkeep found a fact after the facts branch was already written, the fact ended up as a "Needs you" item asking the maintainer to add it to AGENTS.md.

Each repo now gets its workers in two waves (SKILL.md step 4):

1. Work: one upkeep worker and one worker per eligible issue, all running at the same time. Each works in its own worktree at REPO_WORKSPACE/sadr-ROLE/NAME. Its related repos are checked out beside it, so parallel workers never share a checkout.
2. Facts: after every work worker has returned, one facts worker gets their JSON results. It writes every returned fact, plus the inferred_related_repos lines, into sadr/facts. It changes only AGENTS.md (and the CLAUDE.md import line), and it doesn't build anything. It starts only when there is a fact to write.

Other changes:

• Upkeep and issue workers never touch AGENTS.md. They return the facts they checked in a new facts field (subsection, line, checked). They must not put a fact under "Needs you" or ask a maintainer to add one. pr-format.md lists that in what "Needs you" never holds.
• These workers write - pending under ## AGENTS.md. In step 6, the coordinator replaces it with the facts that PR contributed and a link to the facts PR.
• Work workers get the repo's time limit minus 10%, so the facts worker still has time.
• In GitHub Actions, the per-repo session coordinates the two waves with subagents instead of doing all the work itself. The workflows already allow the Agent tool, so they don't change.
• Updated references/agents-md.md, references/permissions.md (worker workspace paths), references/pr-format.md, docs/agents-md.md and CHANGELOG.md.

Testing

• python3 -m unittest discover tests: 184 passed, 2 failed. Both failures (test_report.PreviewTest.test_preview_report_keeps_unknown_spend_null and test_report.PreviewKindsTest.test_kinds_and_account_gaps) are date-dependent and already fail on main. This PR changes no code.
• This changes skill text only. A preview run (workflow_dispatch with preview: true) on one repo with an open sadr issue would exercise both waves end to end.

---

Generated by Claude Code

[pid1]

test (3.10) (and the other test legs) fail on two tests that are unrelated to this PR: test_report.PreviewTest.test_preview_report_keeps_unknown_spend_null and test_report.PreviewKindsTest.test_kinds_and_account_gaps. CI on main has failed the same way on every push since 2026-10-23 (e.g. run 39978666596 on 9831133), and this PR changes only Markdown.

Cause: report.read_bodies dates a preview body by its file mtime (report.py:217), so these tests pass only on a checkout made on 2026-10-22. No fix exists yet. Proposed patch, kept out of this PR: in a setUpClass of both test classes, pin each fixture file's time with os.utime(path, (t, t)) where t is 2026-10-22T12:00Z as a timestamp, before calling read_bodies.

---

Generated by Claude Code