cleanup

/cleanup – Doc Hygiene: HANDOVER cap + lint aggregator

Runs a one-shot hygiene pass on a project's docs to keep them lean and machine-readable: HANDOVER inbox triage and size cap enforcement plus the four existing lint scripts (memory-lint.sh, phase-docs-lint.sh, doc-volume-check.sh, manual-lint.sh) bundled into one consolidated drift report. Use this between phases (after a Gate) or whenever the project-guide warns about HANDOVER size, an unprocessed inbox, stale memory or doc volume drift.

Argument: $ARGUMENTS = [optional: projectdir]

• Without argument: operates on $(pwd).
• With argument: operates on the given project directory.

Flow

1. HANDOVER inbox triage (confirm before removing)

The HANDOVER carries an append-only inbox (## Open Points, see templates/HANDOVER_TEMPLATE.md): working agents drop findings there that fall outside their assignment, when running in the main working tree (a worktree-isolated agent reports the line in its final message instead), and this step is the one place they are cleared again.

Scan docs/HANDOVER.md for lines matching the marker pattern ^- INBOX [|] — match on the marker, not the heading, so entries appended under a differently named heading are still found.

Write the separator as the bracket expression [|], never as a bare |: bare, it is alternation in ERE (grep -E) and in GNU BRE (grep '\|'), where ^- INBOX OR empty matches every line of the file. [|] is a literal pipe in BRE, ERE and Python re alike. Reference command:

grep -c '^- INBOX [|]' docs/HANDOVER.md

It must return the same count with -E added — if the two differ, the pattern is wrong, not the file.

• No matches → report inbox: 0 entries and continue with §2. Do not create the section: a project on an older template stays valid without it. If the ## Open Points heading is missing entirely, mention templates/HANDOVER_TEMPLATE.md once in the report — as a hint, not an action. A fresh project-init HANDOVER is expected to report 0: the template's format example lives inside the section's blockquote (> ) and therefore does not match the marker.
• Matches → split each line on | into marker | date | source | finding | ref and present all entries as a table with one proposed target each. If a line yields more than five fields (someone wrote a literal | into the finding text), keep field 1 as the marker, fields 2–3 as date and source, the last field as ref, and re-join everything in between as the finding — the reference is always last. Never drop the surplus text and never re-cut the line in the file.