docs(bugs): add in-repo bug ledger and agent triage protocol (ADR-0039)#89
Merged
Merged
Conversation
Defects had only half a home: a fixed bug is recorded in the CHANGELOG `Fixed` category and the hotfix/PATCH flow, but a known-open defect and the triage of an incoming report (reproduction, root cause, verdict — including a rejected one) had no durable, reviewable record. For a reference repo whose premise is that every important artifact is versioned and offline-readable (ADRs, patterns, the journal), the investigation of a defect is exactly such an artifact. Add an in-repo bug ledger under docs/bugs/: one Markdown record per defect, BUG-NNNN-<slug>.md under a discovery-date tree docs/bugs/<YYYY>/<MM>/ — a stable monotonic id (cross-referenced from commits/PRs/CHANGELOG) combined with the journal's date-tree foldering to keep any directory small. The ledger is the source of truth (a GitHub issue is referenced, not authoritative). Structured frontmatter carries status/severity/reporter/discovered/affected-versions/fixed-in; the lifecycle is open -> confirmed -> fixed plus the terminal wontfix / duplicate / cannot-reproduce. Codify the agent triage protocol (AGENTS.md §7.7): a record is created only for a verified, reproducible defect; a third-party report is reproduced and root-caused before acceptance, and a report that does not hold up is still recorded as cannot-reproduce/rejected so the triage trail survives. Deciding a defect is real is a judgment task, so it lives in the agent contract, not a hook; structural integrity is enforced by a new `bugs` consistency-lint check (frontmatter, vocabularies, filename↔id and path↔discovered agreement, monotonic ids, index bijection, fixed↔fixed-in). The check is a no-op on an empty ledger, so the gate is green from the moment the scaffold lands. Governance lives in docs/workflow/maintenance.md (defect lifecycle + remediation row); rationale and alternatives in ADR-0039. Relax MD025.front_matter_title so a record may carry both a frontmatter title and a visible H1. Documentation/process/tooling-only; no API change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
5 tasks
danielPoloWork
added a commit
that referenced
this pull request
Jun 15, 2026
## Summary Adds the `2026-06-15` session checkpoint to `docs/journal/`, recording the maintenance session that landed the in-repo bug ledger + triage protocol (PR #89) and the `.bugs` `.gitignore` chore (PR #90). Documentation-only; no code/API change. ## Motivation Per [`AGENTS.md`](AGENTS.md) §7.6 / [ADR-0036](docs/adr/0036-session-journal-extraction.md), a state-changing session closes with a dated journal checkpoint, an index row, and a moved `ROADMAP.md` *Latest checkpoint* pointer. ## Changes - `docs/journal/2026/06/2026-06-15-bug-ledger.md` — the checkpoint (what was done, `master` library surface unchanged, ADRs now 36, how to resume via §7.7). - `docs/journal/README.md` — index row, newest first. - `ROADMAP.md` — *Latest checkpoint* pointer moved to the new entry. ## Design Patterns - None — documentation. ## Verification - [x] `python tools/consistency_lint.py` — OK - [x] `markdownlint-cli2` clean on the three changed files - [ ] Builds / tests — N/A (no code change) ## Documentation Impact - [x] Journal entry + index + ROADMAP pointer updated (the doc change *is* the deliverable) - [x] No README / ADR / CHANGELOG / spec impact 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
danielPoloWork
added
the
documentation
8 tasks
danielPoloWork
added a commit
that referenced
this pull request
Jun 15, 2026
… ADR-0040 (#92) ## Summary Codifies a **PR-metadata policy** so every agent-opened PR also sets a maintainer **assignee**, **exactly one type label** (Conventional-Commit type → label), and the current open **release milestone**. Process/repository-metadata only — no code/API change. ## Motivation PRs carried only a title and body; GitHub's structured metadata (reviewers, assignees, labels, projects, milestone) was unset, leaving the PR list and release view without a type/ownership/release signal. Requested by the maintainer; recorded as [ADR-0040](docs/adr/0040-pull-request-metadata-policy.md). ## Changes - `AGENTS.md` §6.4 — the PR-metadata rule + the Conventional-Commit `type` → label map + the canonical `gh pr create` invocation; a metadata checkbox added to the PR body template. - `docs/adr/0040-pull-request-metadata-policy.md` — decision + rejected alternatives (area labels, rolling milestone, CI auto-labeler, forced reviewer), indexed. - `CHANGELOG.md` — `Unreleased` `Added` entry. - **Out of band (GitHub state, in this session):** created the eight type labels (`feat`/`fix`/`refactor`/`perf`/`test`/`build`/`chore`/`ci`; `docs` reuses `documentation`) and the `v1.1.1` milestone, and backfilled PRs #89–#91 with assignee + type label + milestone. ## Design Patterns - None — process/governance change. ## Verification - [x] `python tools/consistency_lint.py` — OK - [x] `markdownlint-cli2` clean on the four changed files - [x] This PR itself follows the new rule (assignee `@me`, label `documentation` for `docs`, milestone `v1.1.1`) - [ ] Builds / tests — N/A (no code change) ## Documentation Impact - [x] AGENTS.md §6.4 updated; ADR-0040 added + indexed - [x] CHANGELOG.md `Unreleased` updated - [x] No README / spec / patterns impact - [x] PR metadata set — assignee, `documentation` label, `v1.1.1` milestone (§6.4 / ADR-0040) ## Known gaps (documented, not oversights) - **Reviewers** not set — the sole collaborator (`danielPoloWork`) is the PR author and GitHub forbids self-review. Switches on (`--reviewer …`) when a second collaborator/team exists. - **Projects** not set — the `gh` token lacks the `project` scope. Switches on (`--project …`) after `gh auth refresh -s read:project,project` + a board. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an in-repo bug ledger under
docs/bugs/and codifies the agent triage protocol that governs it, closing the gap between "a fixed bug is in theCHANGELOG" and "a known-open / triaged defect has nowhere durable to live." Documentation/process/tooling-only — no API/ABI/build change.Motivation
A fixed defect already has a home (the
CHANGELOGFixedcategory + the hotfix/PATCH flow indocs/workflow/maintenance.md). A known-open defect and the triage of an incoming report (reproduction, root cause, verdict — including a rejected one) had no durable, reviewable record. For a reference repo whose premise is that every important artifact is versioned and offline-readable (ADRs, patterns, the session journal), a defect's investigation is exactly such an artifact. Recorded as ADR-0039.Changes
docs/bugs/ledger — one Markdown record per defect,BUG-NNNN-<slug>.mdunder a discovery-date treedocs/bugs/<YYYY>/<MM>/. The id is a globally-monotonic stable handle (cross-referenced from commits/PRs/CHANGELOG); the date folders (the journal idiom) keep any directory small. The ledger is the source of truth (a GitHub issue is referenced, not authoritative).docs/bugs/README.md(index + format + lifecycle + how-to) anddocs/bugs/template.mdwith structured frontmatter (status/severity/reporter/discovered/affected-versions/fixed-in). Lifecycleopen → confirmed → fixedplus terminalwontfix/duplicate/cannot-reproduce.AGENTS.md§7.7 — the agent triage protocol: a record only for a verified, reproducible defect; a third-party report is reproduced and root-caused before acceptance, and a report that does not hold up is still recorded ascannot-reproduce/rejectedso the triage trail survives.docs/workflow/maintenance.md— a defect-lifecycle section tying the ledger to the existingFixed/hotfix/security flows, plus thebugsremediation row.tools/consistency_lint.py— a newbugscheck: frontmatter keys +status/severity/reportervocabularies, filename↔idand path↔discovered-date agreement, unique non-gapped ids, the index↔files bijection, andfixed⇒fixed-in. No-op on an empty ledger (green from day one)..markdownlint.json—MD025.front_matter_title: ""so a record may carry both a frontmattertitleand a visible H1.docs/README.mdlayout table,AGENTS.mdrepo-layout tree, and aCHANGELOGUnreleasedAddedentry updated to match.Design Patterns
Verification
python tools/consistency_lint.py— OK (and the newbugscheck self-tested against missing-index, wrong-month-folder, and missing-fixed-inrecords, all caught; empty ledger passes)markdownlint-cli2clean across all 103 docs/root Markdown filesDocumentation Impact
docs/README.mdlayout table updatedAGENTS.md§7.3 / ADR-0037)UnreleasedAddedentry added🤖 Generated with Claude Code