[JarryShaw]

• Searched for similar pull requests
• Followed the coding style (make pylint, make mypy, make isort)
• make test passes, and a test case covers the change
• Changelog entry: N/A — centralised in chore(docs): centralise changelog entries for unreleased versions #2483 (process docs, not user-visible)

What is the purpose of your pull request?

• docs — documentation only

---

Description of your pull request and other information

This adds docs/source/contributing/maintenance.rst (Maintenance Workflow) to the toctree next to contributing/workflows. The page sets out the maintenance workflow the automation runs on this repository. It is written to be read by a person and handed to an agent as a brief.

It contains seven mermaid diagrams covering:

• actors and roles, and the three recurring loops (decision watch, board sweep, notes checkpoint);
• the issue and review: label state machines;
• the pull request lifecycle, including the needs-changes loop;
• the decision loop, the post-merge routine and the main-CI watch.

It also covers the throttles and guards, the brief template, what each helper script does, a bootstrapping checklist, and a table of failure modes with the guard for each. Label meanings link to process.rst rather than being restated, and rulings are paraphrased.

A PR rather than a direct push, because the page codifies process. It adds no docs warnings (95 on main, 95 here). The docs-reading project tests and project half 1 pass.

Closes #2782

[JarryShaw]

NEEDS CHANGES at fa42839c9. A Sonnet cross-review found the page accurate against the workflow's sources, its citations sound (#2243 and #2449 hold their rulings) and public-safe. It wants these changes:

• Trim repetition. Cut the failure-mode table to one line per row with a section link, and keep only the label transitions, linking process.rst for what the labels mean.
• Fix the wording.
  • Drop the unsourced reason given for the loop cadences.
  • The review budget is about 25 minutes, and anything unfinished reports UNVERIFIED.
  • The file cap is about 2 GiB and soft only.
  • Check the abandoned-work transition against process.rst.
• Fill reuse gaps, one line each: pushes with a lease, --onto rebases checked by patch-id, the CI watch on good-to-go PRs, milestones set only by automation, the recommended comment and body lengths, and commenting on every hold.

[JarryShaw]

GOOD TO GO at 575678834. The same Sonnet reviewer read the round-1 delta and confirmed each change against the workflow's sources:

• the failure-mode table is now pointers to sections, and label meanings link to process.rst;
• the unsourced cadence reason is gone, and the file cap is soft-only;
• the seven reuse lines each trace to a rule.

Two items were declined, and I checked both declines against the sources: the review-budget cutoff wording, and wip returning to pending on abandoned work (process.rst). The docs build adds no warnings (95 on main, 95 here), all diagrams render, and the docs-reading project tests pass.