Add README cleanup task

This commit is contained in:
Dandaedre 2026-10-04 00:38:08 +02:00
parent 3d83737823
commit b73ef8fc47
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
2 changed files with 146 additions and 0 deletions

View File

@ -15,6 +15,19 @@ reference it from a project task. The receiving agent must still read that
project's own instructions and adapt the brief to its existing CI, tools,
metadata, and commit conventions.
## Task catalog
- [`add-jenkins.task.md`](tasks/add-jenkins.task.md) adds a maintainable Jenkins
pipeline.
- [`ci-coverage-badges.task.md`](tasks/ci-coverage-badges.task.md) generates and
publishes version, test, and coverage badges.
- [`make-release-script.task.md`](tasks/make-release-script.task.md) integrates
a safe `rust_realease` wrapper.
- [`readme-cleanup.task.md`](tasks/readme-cleanup.task.md) streamlines a README,
links advanced documentation, and verifies CI-backed badges.
- [`semi-harden-ci.task.md`](tasks/semi-harden-ci.task.md) adds focused Rust
dependency security and policy gates.
## Publishing
Tasks are private to the repository by default:

View File

@ -0,0 +1,133 @@
<!-- Purpose: Make a repository README concise, accurate, and easy to navigate. -->
<!-- Scope: Keep essential onboarding in the README, move advanced detail into docs when useful, and verify CI-backed badge claims. -->
# Clean up a repository README
Apply this task to one repository at a time. Read its local agent instructions,
README, documentation tree, package metadata, and CI configuration before
editing. Preserve unrelated work, follow the repository's commit policy, and
do not push, trigger CI, or publish assets unless explicitly requested.
## Establish the documentation contract
Treat the repository and its executable configuration as the source of truth.
Before rewriting prose:
1. identify the intended audience and the project's current purpose, support
status, canonical owner and project name, default branch, and license;
2. run or otherwise verify the shortest supported install, build, and usage
path rather than copying stale commands;
3. locate authoritative contributor, configuration, deployment, release,
troubleshooting, security, and architecture documentation;
4. inspect inbound links, relative links, anchors, badges, screenshots, and
commands so useful references are not silently broken; and
5. note content that is duplicated, obsolete, speculative, or too detailed for
first-time readers.
Do not invent features, compatibility promises, commands, support channels, or
publication state. Preserve legally or operationally required notices. Keep
project-specific terminology where it is meaningful, and explain it before
using unexplained abbreviations.
## README structure
Make the README a concise entry point. Prefer this order when it fits the
project, adapting or omitting sections rather than creating empty headings:
1. project title and verified status badges;
2. one short explanation of what the project does and who it is for;
3. prerequisites and the smallest working installation or setup path;
4. a minimal usage example with its expected result;
5. links to configuration and task-oriented documentation;
6. development and contribution commands; and
7. license and support information.
Use descriptive link text and relative links for files within the repository.
Keep heading levels ordered, use one term consistently for each concept, label
code fences, and keep commands directly runnable from the stated directory.
Avoid tables of contents for short READMEs, repeated navigation blocks,
marketing filler, exhaustive option references, and prose that merely restates
command output.
Preserve existing information until it is proven obsolete or has a clear new
home. A shorter README is not successful if maintainers lose necessary
operational knowledge.
## Advanced documentation
Keep the basic install and first-use path in the README. When advanced material
makes that path hard to scan, move cohesive topics into the repository's
existing documentation structure. If no suitable structure exists and the
material justifies a separate page, create a small `docs/` area following the
project's naming conventions and add an **Advanced** section to the README that
links directly to each new page.
Advanced topics can include architecture, uncommon configuration, production
deployment, CI internals, release procedures, performance tuning, and detailed
troubleshooting. Do not move essential prerequisites, safety warnings, or the
only working example out of the README. Ensure moved pages link back or provide
enough context to be usable when opened directly. Update all affected relative
links and avoid creating placeholder pages.
## Verify CI-backed badges
Determine whether the README is expected to show the current default-branch
version, test, and coverage badges. Resolve `<asset-origin>`, `<owner>`,
`<project>`, and `<default-branch>` from the canonical repository and CI
configuration, not merely from the checkout directory. Check these exact
public URLs after substitution:
```text
<asset-origin>/coverage/<owner>/<project>/<default-branch>/version.svg
<asset-origin>/coverage/<owner>/<project>/<default-branch>/test.svg
<asset-origin>/coverage/<owner>/<project>/<default-branch>/coverage.svg
```
Verification must cover the complete path from generation to publication:
- inspect CI and tracked scripts to confirm all three SVGs are generated from
authoritative version, test, and coverage results;
- confirm CI validates the files as regular and nonempty, archives exactly the
intended badges, and publishes them only from the default branch to the path
represented by the public URLs;
- check that the default branch, owner, project, filenames, asset mount, and
public origin agree across CI, scripts, server documentation, and README;
- if network access is available, request each public URL, require a successful
response with SVG content, and parse it as XML; distinguish a live but stale
badge from a missing, invalid, or unpublished badge; and
- verify badge alt text is meaningful and place the three badge images directly
below the README title without linking them to a report CI does not retain.
Do not treat the presence of a README image URL, a workspace SVG, or an archive
pattern as proof that CI publishes the badge. Do not claim the public badges are
live until a successful default-branch build has generated and published all
three and their public responses have been checked.
If the project intentionally provides these badges and the existing pipeline
is incomplete, make the smallest in-scope correction when it is straightforward
and verify it. For a missing or materially broken badge pipeline, apply
[`ci-coverage-badges.task.md`](ci-coverage-badges.task.md) as a separate logical
change instead of embedding a large CI redesign in the README cleanup. Until
publication is verified, remove or clearly avoid introducing broken badge
images and report the exact gap.
## Verification
Before committing:
1. render or preview the README and every new documentation page;
2. check local links, anchors, image references, and code-block formatting with
the project's Markdown tooling when available;
3. run every changed quick-start and development command that is safe and
locally reproducible, and state which commands could not be exercised;
4. search for stale references to renamed or moved headings and files;
5. verify the three badge generation and publication paths as described above,
recording whether the public URL check was performed or unavailable;
6. inspect the diff for lost information, accidental reflow, project identifiers
copied from examples, secrets, and unrelated edits; and
7. commit the README, any moved documentation, and directly related fixes as
focused, reviewable changes.
Report the final README organization, documentation moved or removed, commands
and links checked, the status of each expected badge URL, the commit ID, and any
CI or network verification that remained unavailable.