Retrospective: workflow & guideline-adherence improvements

[PBNZ]

Context

A retrospective across the maintainer's active repos — one multi-person project plus eight
single-maintainer repos at various stages of standard adoption — examined where issue/project
management broke down, where docs went stale, and where humans or AI agents didn't follow the
standard's own guidelines, and why. All findings are generalised and anonymised; no repo is
identified.

The dominant patterns found:

1. Resume-state docs decay the moment the build phase ends, or never exist at all — the standard
   asks for them to be kept current but neither requires the file nor checks it.
2. Changelogs are written well but releases are never cut — [Unreleased] becomes a terminal
   state even where release machinery exists.
3. Commit↔issue traceability is near zero outside the one board-driven project, and inside it the
   documented auto-close keyword convention once skipped a human verification gate.
4. Human/agent collaboration rules (board-move timeliness, pickup/handoff, signatures, credential
   preflight) were invented ad hoc mid-project after each failure instead of being part of the
   standard.
5. Repos drift from the standard file set silently (missing shim file, relocated files,
   undocumented substitutes) — deviations are only discoverable by archaeology.
6. There is no labelling standard at all.

Tasks

• Review the individual improvement issues spawned from this retrospective:
  • Define a RepoKit labelling standard (issues/PRs) with per-repo bootstrap #11 — labelling standard (finding 6)
  • Make the resume-state doc a required, checked Core artifact #12 — resume-state doc required + checked (finding 1)
  • "[Unreleased] is not a terminal state" — add release-cutting triggers to the standard #13 — release-cutting triggers (finding 2)
  • Commit-issue traceability: standardise Refs #NN and defuse auto-close keywords #14 — commit-issue traceability + auto-close guard (finding 3)
  • Add an agent-collaboration reference: board discipline, pickup/handoff, signatures, preflight #15 — agent-collaboration reference (finding 4)
  • Variance declarations + a compliance self-check (repokit lint) #16 — variance declarations + compliance self-check (finding 5)
  • Session-end hygiene: unmerged branches, mega-commits, state-doc churn #17 — session-end hygiene (findings 1/5 tail)
• For each: accept into the standard, adapt, or decline with a short rationale on the issue.
• Close this issue when every spawned issue is triaged.

Acceptance criteria

• Every finding above is covered by exactly one linked issue (or an explicit "declined" note).
• Accepted changes land in the standard's reference docs/checklists, not as loose advice.

— 🤖 Claude, on behalf of @PBNZ

[PBNZ]

Status: all seven spawned issues triaged — every one accepted (two with minor adaptations, noted on the issues). Implementation is up as PR #18, one Refs #NN commit per issue, rationale recorded in ADR-0007.

Per the acceptance criteria here: every finding is covered by exactly one linked issue, and all accepted changes land in the standard's reference docs/checklists, not as loose advice.

Remaining (human): review/merge PR #18, verify each of #11–#17 post-merge and close them, then close this issue. Nothing auto-closes — #14's own rule, applied here first.

— 🤖 Claude, on behalf of @PBNZ

[PBNZ]

Status update: the day-2 addenda are triaged and landed on the same PR #18 — Refs #19 (fleet overlay), Refs #20 (org-migration checklist), and the two #15 addenda comments (closing-force gestures, three-audience instructions). All accepted; ADR-0007 extended with the addenda and the adaptation rationale.

Remaining (human) is unchanged, now covering nine: review/merge PR #18, verify and close #11–#17, #19, #20, then this issue.

— 🤖 Claude, on behalf of @PBNZ