diff --git a/.agents/agents/issue-implementer.md b/.agents/agents/issue-implementer.md index ce5813d0e..e0840ae4f 100644 --- a/.agents/agents/issue-implementer.md +++ b/.agents/agents/issue-implementer.md @@ -19,6 +19,8 @@ pull request. ## Responsibilities - Resolve issue and branch context before editing code. +- Check whether any earlier PR for the issue or branch is already closed + before assuming prior branch names are safe to reuse. - Keep the diff focused on the selected issue. - Run the smallest relevant verification first, then the broader gate when warranted. @@ -34,6 +36,8 @@ pull request. ## Boundaries - Do not batch unrelated issues into the same branch or PR. +- Do not revive a deleted historical branch for follow-up work; prefer opening + a bug issue and starting a fresh branch/PR. - Do not skip verification before publishing a PR update. - Do not guess through vague acceptance criteria when the issue is not actionable enough to implement safely. diff --git a/.agents/agents/review-guardian.md b/.agents/agents/review-guardian.md index d70bb85bc..5a107513b 100644 --- a/.agents/agents/review-guardian.md +++ b/.agents/agents/review-guardian.md @@ -25,6 +25,9 @@ and generated-output drift before human review time is spent. - Treat packaged skills, project agents, workflow wrappers, local actions, changelog entries, wiki output, and generated reports as first-class review surfaces when touched. +- Treat ``.github/wiki`` pointer changes as workflow-managed state when they + line up with wiki preview or wiki maintenance automation, rather than as + automatic evidence of accidental scope creep. - Stay reusable across this repository and consumer repositories that synchronize DevTools assets. diff --git a/.agents/skills/github-pull-request/SKILL.md b/.agents/skills/github-pull-request/SKILL.md index a1a589c64..12fcad05e 100644 --- a/.agents/skills/github-pull-request/SKILL.md +++ b/.agents/skills/github-pull-request/SKILL.md @@ -20,6 +20,10 @@ Use this skill to take a Fast Forward issue from "ready to implement" to an open - Keep one branch and one PR per issue. - Branch from `main` or the repository integration branch, never from another feature branch. - When returning to `main` before starting a new implementation, always fetch and fast-forward from the remote before creating the next feature branch so release files, changelog state, and generated artifacts start from the latest published baseline. +- Before pushing or reopening prior work, verify whether an earlier PR for the + issue or branch is already closed. If the earlier branch has been deleted or + the PR is closed, prefer opening a follow-up bug issue and publishing a new + branch and PR instead of reviving the old branch name. - Prefer local `git` for checkout, commit, and push. - Prefer connector-backed GitHub data for issue and PR context when available. - Use `phpunit-tests`, `package-readme`, and `sphinx-docs` when the change clearly affects tests or documentation. @@ -41,6 +45,9 @@ Use this skill to take a Fast Forward issue from "ready to implement" to an open - Do not batch unrelated issues into one branch or PR. - Do not create a duplicate PR if the current branch already has one. +- Do not push new follow-up work onto a previously closed PR branch that has + already been deleted upstream; open a bug issue and start a fresh branch/PR + instead. - Do not open a PR before running the relevant verification commands. - Do not skip a notable changelog update when the implementation changes public behavior, release automation, or repository workflows in a way users or maintainers would expect to see called out. - Do not proceed to the next issue if the repository is dirty from unfinished work. diff --git a/.agents/skills/github-pull-request/references/context-routing.md b/.agents/skills/github-pull-request/references/context-routing.md index 60771cadf..f2b841573 100644 --- a/.agents/skills/github-pull-request/references/context-routing.md +++ b/.agents/skills/github-pull-request/references/context-routing.md @@ -34,3 +34,5 @@ Before starting implementation, confirm: - the base branch exists locally and can be updated - the issue is specific enough to implement - authentication for the required GitHub operations is available if a PR will be opened +- any earlier PR tied to the intended branch or issue is still open before + treating that branch as reusable diff --git a/.agents/skills/github-pull-request/references/pr-drafting.md b/.agents/skills/github-pull-request/references/pr-drafting.md index 53d82b12b..256143651 100644 --- a/.agents/skills/github-pull-request/references/pr-drafting.md +++ b/.agents/skills/github-pull-request/references/pr-drafting.md @@ -8,6 +8,10 @@ Before creating a new PR, check whether the current branch already has an open P - If a PR already exists, update it instead of creating a duplicate. - If no PR exists, create one against `main` or the repository's integration branch. +- If an earlier PR for the same issue or historical branch already exists but + is closed, do not assume that branch should be reused. When the old branch + was deleted or the previous PR represents finished work, open a follow-up + bug issue and publish a fresh branch and PR. ## Template Rule diff --git a/.agents/skills/pull-request-review/SKILL.md b/.agents/skills/pull-request-review/SKILL.md index ef1fa5908..d17021d4a 100644 --- a/.agents/skills/pull-request-review/SKILL.md +++ b/.agents/skills/pull-request-review/SKILL.md @@ -35,6 +35,9 @@ possible. - Treat ``.github/workflows``, ``resources/github-actions``, ``.github/actions``, ``.agents/skills``, ``.agents/agents``, ``README.md``, ``docs/``, ``CHANGELOG.md``, and ``.github/wiki`` as high-signal review surfaces. +- When ``.github/wiki`` moves, verify whether the wiki preview or wiki + maintenance workflow is expected to refresh the submodule pointer before + treating that change as unrelated drift or scope creep. - Prefer precise repository file references in every finding. - Review what changed, but reason about downstream consumer impact when the PR touches packaged assets or synchronized defaults. diff --git a/.agents/skills/pull-request-review/references/surface-priorities.md b/.agents/skills/pull-request-review/references/surface-priorities.md index 438843db9..76683ddfc 100644 --- a/.agents/skills/pull-request-review/references/surface-priorities.md +++ b/.agents/skills/pull-request-review/references/surface-priorities.md @@ -22,7 +22,10 @@ Additional Fast Forward review surfaces - ``README.md`` and ``docs/`` for onboarding, command, or workflow drift. - ``CHANGELOG.md`` for notable user-facing or automation-facing changes. -- ``.github/wiki`` when generated wiki output is touched. +- ``.github/wiki`` when generated wiki output is touched. In this repository, + the wiki preview and wiki maintenance workflows can legitimately move the + submodule pointer as workflow-managed state, so confirm whether the change + matches that automation before flagging it as unrelated drift. - ``resources/`` when synchronized templates or packaged defaults changed. Typical review questions diff --git a/.github/wiki b/.github/wiki index c1c3fa748..e4312aab8 160000 --- a/.github/wiki +++ b/.github/wiki @@ -1 +1 @@ -Subproject commit c1c3fa7484013ee7d3062451453b87e791bae55e +Subproject commit e4312aab8d185e3478d1b0adbdc6d90dcfa6e042 diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d92a11a1..239e8b1cc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed +- Teach the review and pull-request agent skills to treat workflow-managed wiki pointer updates as expected state and to prefer fresh follow-up issues plus PRs over reviving closed deleted branches (#147) - Require GitHub issue write readback verification in the github-issues skill (#165) - Standardize cache flags and nested cache-dir propagation across cache-aware commands (#162)