Skip to content

2026-06-15-bug-ledger.md

Latest commit

 

History

History
12 lines (10 loc) · 3.2 KB

2026-06-15-bug-ledger.md

File metadata and controls

12 lines (10 loc) · 3.2 KB
Raw

2026-06-15 — Bug ledger & triage protocol (maintenance session)

Session checkpoint — part of the session journal. Checkpoints live outside ROADMAP.md per ADR-0036.

  • Done in this session — added the in-repo bug ledger and the agent triage protocol that governs it (PR #89, merged), plus a one-line .gitignore chore (PR #90, merged). The ledger: one Markdown record per defect at docs/bugs/<YYYY>/<MM>/BUG-NNNN-<slug>.md — a globally-monotonic stable id combined with the journal's date-tree foldering — with docs/bugs/README.md (index + lifecycle) and docs/bugs/template.md. The ledger is the source of truth (a GitHub issue is referenced, not authoritative). Decision recorded in ADR-0039; governance in docs/workflow/maintenance.md (defect-lifecycle section); agent rule in AGENTS.md §7.7. A new bugs check in tools/consistency_lint.py enforces frontmatter, vocabularies, filename↔id and path↔discovered agreement, monotonic ids, the index bijection, and fixed⇒fixed-in (no-op on an empty ledger). .markdownlint.json relaxes MD025.front_matter_title so a record may carry both a frontmatter title and a visible H1.
  • Library state on master — unchanged. This session is documentation / process / tooling only; no code, public C ABI, C++ surface, or build change. The v1.1.0 static archive is byte-identical. The CHANGELOG [Unreleased] block now carries the bug-ledger Added entry, pending the next release.
  • ADRs accepted to date — 0001–0039. Total: 36 (this session added 0039).
  • Patterns catalogue — unchanged: eleven Implemented; no new pattern (the ledger is a process/tooling change, not a code pattern).
  • Spec Coverage Map — unchanged: fifteen rows ✅ (no spec row maps to this maintenance work).
  • Versions — v1.1.0 is the latest released version; these changes sit unreleased on master. Per AGENTS.md §7.3 / ADR-0037 this is a maintenance change, not a milestone — recorded in the CHANGELOG, justified by ADR-0039, no roadmap item.
  • Open issues / follow-ups — none blocking. The bug ledger is empty (no defects recorded yet — green by design). Standing note: the pre-1.0 milestone GitHub Releases v0.4.0/v0.5.0/v0.6.0 remain Draft (old, likely intentional — do not publish without asking).
  • Resume the next session with — the bug ledger is live. When asked to hunt for bugs, create a docs/bugs/ record only for a verified, reproducible defect; when a third party reports a bug, reproduce and root-cause first, recording an unconfirmed report as cannot-reproduce/rejected — per AGENTS.md §7.7. Run python tools/consistency_lint.py (now with the bugs check) before drafting any PR. Maintained-product governance otherwise unchanged (docs/workflow/maintenance.md).