missing_docs: keep at most one bookkeeping PR open

.agents/skills/missing_docs/SKILL.md

@@ -423,9 +423,40 @@ their area. Do NOT bundle unrelated features into a single mega PR.
   snapshot is a wholesale regen. Put every `Flag -> page` mapping, ignore/`internal`/
   `gated:` entry, and the `--update-snapshot` regen into one bookkeeping PR. Its mappings
   may point at pages that land in the sibling feature PRs — map hygiene only requires the
-  target page to exist on the base branch, so the bookkeeping PR is independently
-  mergeable in any order. If a run documents exactly one feature, fold its map + snapshot
-  changes into that single PR and skip the companion.
+  target page to exist on the base branch, so the bookkeeping PR merges independently of
+  those feature PRs, in any order. If a run documents exactly one feature, fold its map +
+  snapshot changes into that single PR and skip the companion.
+- **Keep at most one bookkeeping PR open. Extend the open one rather than opening a
+  second.** The independence above holds against *feature* PRs; it does not hold against
+  another bookkeeping PR. Two of those edit the same shared files, and
+  `surface_snapshot.json` is regenerated wholesale, so a conflict between them cannot be
+  resolved by hand — it has to be regenerated on the merged tree. Look for an existing one
+  before opening yours:
+
+  ```bash
+  gh pr list --state open --search '"bookkeeping for" in:title' \
+    --json number,headRefName,title,reviewDecision
+  ```
+
+  Match on the quoted phrase, not the two words separately. An unquoted
+  `missing_docs bookkeeping in:title` search ANDs the two words anywhere in the title, so
+  it also matches this rule-only PR's own title ("...keep at most one bookkeeping PR
+  open") — the next run would then check out and extend this PR's branch instead of a real
+  bookkeeping PR.
+
+  If one exists and `reviewDecision` is not `APPROVED`, check out its branch and add this
+  run's map entries and ledger rows on top, then re-run `check_new_release.py --commit` and
+  `--update-snapshot` there so the marker and snapshot stay a single regen covering every
+  release the PR now carries. Update its title and body to name them all. The one
+  exception: if `reviewDecision` is already `APPROVED` (it's about to merge), wait for the
+  merge and branch from the result instead of extending it.
+
+  For the search to find it, title every bookkeeping PR `chore(missing_docs): bookkeeping
+  for <version>` and name its branch `missing-docs/bookkeeping-<version>`. The title keeps
+  the repo's existing prefix style (see `create_pr` → Best Practices) while carrying the
+  `bookkeeping for` phrase the search matches on. #614 and #624 used two different naming
+  schemes and neither run looked for the other's PR, which is how both ended up adding the
+  same two `/factory` map entries.
 - **API spec gaps stay separate** — released endpoints go through the `sync-openapi-spec`
   skill as their own change, never bundled into a feature PR.
 - **Validate once, then split.** Run `npm run build` on the combined working tree (all
@@ -467,10 +498,13 @@ with the product. Each run:
      --diff --output /tmp/docs_audit.json
    ```
 3. **Triage**: read `references/changelog_decisions.md` first and drop any changelog item
-   already decided. Then work through `surface_changes` and `changelog_review` (what
-   changed since last run), then standing coverage findings (high → medium → low)
-   across all categories: features, CLI, API, slash commands, settings, stale doc
-   references, unlisted pages, map hygiene, staleness.
+   already decided. Read the ledger and surface map as they stand on any open bookkeeping
+   PR too, not only the copies on `main` — a verdict recorded in an unmerged PR is still a
+   verdict, and re-triaging it burns the run and produces duplicate map entries. Then work
+   through `surface_changes` and `changelog_review` (what changed since last run), then
+   standing coverage findings (high → medium → low) across all categories: features, CLI,
+   API, slash commands, settings, stale doc references, unlisted pages, map hygiene,
+   staleness.
 
    **Apply `.agents/references/docs-worthiness-criteria.md` to every remaining item
    before deciding anything else.** The default is no docs; the burden is on the change
@@ -522,13 +556,14 @@ with the product. Each run:
    owners as a partial result worth naming in the run output.
 8. **Open one PR per feature** following the PR strategy above (not a single mega PR):
    one focused PR per documented feature (grouping only features that share a doc file or
-   owner), each carrying its content design plan as a section in the PR body, plus a
-   single companion audit-bookkeeping PR for all `feature_surface_map.md`,
-   `changelog_decisions.md`, `last_release_processed.json`, and `surface_snapshot.json`
-   changes. Use the `create_pr` skill: every drafting PR body opens with the required
-   `## What this feature does` summary, and every PR gets its owning reviewer requested
-   per step 7 before the run is done. Summarize remaining (deferred) findings in the
-   relevant PR body so nothing is silently dropped.
+   owner), each carrying its content design plan as a section in the PR body, plus the
+   run's bookkeeping changes to `feature_surface_map.md`, `changelog_decisions.md`,
+   `last_release_processed.json`, and `surface_snapshot.json`. Extend the open bookkeeping
+   PR if there is one; open a new one titled `chore(missing_docs): bookkeeping for
+   <version>` only if there is not. Use the `create_pr` skill: every drafting PR body
+   opens with the required `## What this feature does` summary, and every PR gets its
+   owning reviewer requested per step 7 before the run is done. Summarize remaining
+   (deferred) findings in the relevant PR body so nothing is silently dropped.
 
 A run that gates out every candidate is a successful run. It opens no feature PRs and
 only the bookkeeping PR recording the verdicts. Do not manufacture work to justify the
@@ -557,8 +592,15 @@ Recommended scheduled-agent prompt (copy when setting up the agent):
 > source files behind each addressed finding. Open one focused PR per documented feature
 > (grouping only features that share a doc file or owner), each opening with the required
 > "## What this feature does" summary and carrying the content design plan as a section in
-> its body, plus a single companion bookkeeping PR for the feature_surface_map.md,
-> changelog_decisions.md, last_release_processed.json, and surface_snapshot.json changes.
+> its body, plus the bookkeeping changes to feature_surface_map.md,
+> changelog_decisions.md, last_release_processed.json, and surface_snapshot.json. Before
+> opening a bookkeeping PR, search for an open one with gh pr list --state open --search
+> '"bookkeeping for" in:title' --json number,headRefName,title,reviewDecision — the quoted
+> phrase, not the two words separately, so the search doesn't also match this rule-only
+> PR's own title. Extend that branch instead of opening a second, unless reviewDecision is
+> already APPROVED, in which case wait for the merge and branch from the result; two open
+> bookkeeping PRs conflict on a snapshot that is regenerated wholesale. Title a new one
+> "chore(missing_docs): bookkeeping for <version>".
 > Request the resolved owner as reviewer on every PR with gh pr edit --add-reviewer,
 > falling back to dannyneira when nothing resolves, and verify the requested-reviewers
 > list is non-empty before you finish — a PR with no requested reviewer is an incomplete