feat: seed PRs record their standards ref, supersede older seed PRs, and refuse downgrades (#1925)

[don-petry]

Summary

scripts/seed-repo-template.sh now says where a seed came from, keeps one seed PR open, and refuses to downgrade a template file.

• Provenance. The seed PR body states the resolved standards ref, how it was chosen (channel, explicit STANDARDS_REF, HEAD fallback or local) and the commit. A hidden marker carries the same three values. A reused PR's body is rewritten on each run.
• Supersede. When several seed-scaffold/* PRs are open, the newest is kept and each older one is closed with a comment linking it.
• No downgrades. A file that differs from the run's emission but matches the emission at standards HEAD is refused, with "standards channel is behind the template — promote standards".
• Operator procedure. docs/release/seeding-repo-template.md documents how and when to seed.

Closes #1925 ("seed-repo-template.sh: seed PRs record no standards ref, never supersede each other, and can regress repo-template").

Also in this PR

One sentence in AGENTS.md for issue #1927: seed-repo-template.sh has one home, this repo. The rename that removes the other same-named script is petry-projects/.github#1294, which closes #1927.

Builds on PR #2244

The no-downgrade check reuses the ancestry read, _template_drift_compare, that PR #2244 (issue #2237) added. That PR is merged, and this branch is up to date with main, so the diff here is this PR's four files only.

Problem

On 2026-09-23 a seed PR generated from standards/v1-stable (then v1.0.0) would have removed the merge_group trigger a previous seed had shipped. Five seed PRs were open at once, and none said which ref it used.

Acceptance criteria

1. Provenance: done as described above.
2. Supersede: issue seed-repo-template.sh strips the commercial-support sections from repo-template on every run — its README and BOOTSTRAP baseline predates the commercial-support standard, and stale seed PRs pile up #2233 landed while this was in progress and already makes a run update an open seed PR in place. This PR adds the missing part: the other open seed PRs are closed, each with a link to the kept one. A PR that cannot be closed fails the run and is named.
3. No downgrades: done. If every differing file is refused, no PR is opened and the empty branch is removed.
4. Scheduled home: a documented operator procedure, as chosen by the maintainer, not a workflow.

Failure handling

• If the standards HEAD commit, its relation to the resolved ref, or the emission at HEAD cannot be read, the seed aborts. It never treats "cannot tell" as "not ahead".
• If this run's PR number cannot be identified, no older seed PR is closed, and the run says so.
• If the open pull requests cannot be listed, the seed stops before it writes anything. It could not rule out an open seed PR.
• Every standards file is fetched at the commit recorded in the PR body, not through the ref name, so a channel that moves mid-run cannot make the two disagree.
• Only a file that would be overwritten pays for the newer-commit comparison. With a local STANDARDS_DIR there is no ref, so the check is skipped.

Risk

Medium. This changes a script that writes to petry-projects/repo-template.

• New writes: gh pr edit on the kept seed PR, gh pr close on older seed-scaffold/* PRs, and a ref DELETE of a branch this run created and left empty.
• gh pr close only ever targets a PR whose head branch starts with seed-scaffold/.
• A run that finds nothing to write used to fail at gh pr create. It now exits 0 with "no PR opened".

Test plan

• bats tests/test_seed_repo_template.bats: 99 pass, 1 fails. The failure is test 59 (issue seed-repo-template.sh strips the commercial-support sections from repo-template on every run — its README and BOOTSTRAP baseline predates the commercial-support standard, and stale seed PRs pile up #2233's sed -i test), which fails on macOS sed on main too. 34 tests are new. Three of them run the real HEAD read, the real ancestry read and the real child emission with only gh replaced.
• Counterfactual: with the seeder reverted to main, 18 of the new tests fail.
• bats tests/template_stub_drift.bats tests/agent_ingress_reference.bats tests/test_lint_main_push_trigger.bats: all pass.
• find scripts -name "*.sh" -exec shellcheck --severity=warning -x {} +: clean. markdownlint-cli2 on the new doc: 0 errors.
• Run against live GitHub with real gh on 2026-10-11, DRY_RUN=true (read-only):
  • Default channel: every file SKIP or PRESERVE except README.md (UPDATE). Re-run after the commit pin was added: same result.
  • STANDARDS_REF=standards/v1.0.0: agent-shield.yml, dependency-audit.yml, copilot-setup-steps.yml, dependabot-rebase.yml and dev-lead.yml are reported would REFUSE … the template is ahead, with the channel-behind warning. That is the September regression, now refused.
• Not run: a live (non-dry) seed. The PR create, edit, close and branch delete paths are covered with a stubbed gh only.

Rollback

Revert this PR. A seed PR opened by this version stays valid; its extra body text is harmless.

Monitoring

The next real seed of repo-template: its PR body should show the "Standards provenance" block, and only one seed-scaffold/* PR should be open afterwards.

Interaction contract

• N/A — this PR does not add or change an agentic role.

Checklist

• shellcheck scripts/*.sh passes for any changed shell scripts.
• Docs updated where behavior or standards changed.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 27 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 15782ec2-daf6-4a1b-89ee-13d96fd79573

---

📥 Commits

Reviewing files that changed from the base of the PR and between 82461dc and 70a1c74.

---

📒 Files selected for processing (4)

• AGENTS.md
• docs/release/seeding-repo-template.md
• scripts/seed-repo-template.sh
• tests/test_seed_repo_template.bats

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[codeant-ai]

CodeAnt Nitpicks

4 code suggestions

1. STANDARDS_DIR bypasses the HEAD and ancestry checks, so content matching standards HEAD can be overwritten by a different local emission instead of refused.

Comment mismatch · AGENTS.md:533-534

---

2. When the channel ref is unavailable, _resolve_standards_ref falls back to default-branch HEAD, so leaving STANDARDS_REF unset does not guarantee a channel-based seed.

Comment mismatch · AGENTS.md:527

---

3. For STANDARDS_DIR, the PR body records unknown as the commit; this claim promises a commit although local-source provenance has none.

Comment mismatch · AGENTS.md:529

---

4. The body records _STD_SHA, but _fetch_standard fetches through mutable _STD_REF; if that ref moves during generation, the PR claims a commit different from its content.

Api mismatch · scripts/seed-repo-template.sh:1028

[codeant-ai]

CodeAnt PR Risk: Low Risk

• The PR appears safe to merge; the prior concerns about missed seed PRs and stale dated branches are addressed in the current code.
• The seeder pins reads to the recorded standards commit, refuses verified downgrades, and adds tests for these behaviors.

Assessed commit: 70a1c7445f98

[don-petry]

dev-lead is withholding action on this item.

It is labeled dev-lead:hands-off (deliberately kept off-limits to dev-lead (e.g. changes to the dev-lead automation itself)), so dev-lead will not pick it up while that label is present. This notice is posted once so the withhold is visible rather than looking like a stalled run.

To re-enable automated pickup: remove the dev-lead:hands-off label.

[don-petry]

QA Lead — test-risk advisory

Risk tier: MEDIUM. The script can now edit and close PRs and delete branches on repo-template, but it fails closed, gh pr close only touches seed-scaffold/* branches, and the new tests are strong (22 new, 18 of which fail against main).

What I'd shore up (highest leverage first):

• The ahead/behind contract is only tested against a mock. Every AC3 test stubs out the standards HEAD SHA, _template_drift_compare (from feat: implement issue #2237 — template-drift AHEAD detection: two narrow misclassifications and three untested paths left open by PR 2219 #2244) and the emission at HEAD. Neither _seed_emit_at re-running the script with STANDARDS_REF=<sha> and errors silenced (2>/dev/null), nor the meaning of the ahead relation, is checked against the real code. Add one test that runs the real compare and emit (stubbing only gh), so a change to feat: implement issue #2237 — template-drift AHEAD detection: two narrow misclassifications and three untested paths left open by PR 2219 #2244's semantics breaks a test rather than silently turning off the refusal.
• The leftover dated branch with nothing written is untested. Here branch_created=0, so the run skips the "no PR opened" exit and goes on to gh pr create on a branch that may now match the base. Pin down what should happen: a clean exit or a clear error.
• The failure exits after a PR is opened have no end-to-end tests. One case is a pr create URL that won't parse, so the kept PR is unknown. The other is a failed gh pr edit. Both should exit non-zero and close nothing; today only the unit test for _seed_close_superseded covers this.
• The --limit 1000 test just greps the source. Swap it for a stub that returns more than 100 open PRs with a seed PR last.

Escalate? No. The first live (non-dry) seed is the real integration test, so watch it as the PR's Monitoring section says.

Advisory only — I comment, I do not change code. Ground: BMAD Test Architecture
(bmad-tea v1.19.0). Opt out on this item with the qa-lead:hands-off label.

[donpetry-bot]

Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-10-11T04:14:10Z.

[donpetry-bot]

Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-10-11T04:14:12Z.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[donpetry-bot]

Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-10-11T15:43:51Z.