diff --git a/docs/TICKETS.md b/docs/TICKETS.md new file mode 100644 index 0000000..6979217 --- /dev/null +++ b/docs/TICKETS.md @@ -0,0 +1,62 @@ +# Aborist tickets — index + +Aborist uses a flat `ticket-NNNNNN-.md` convention for actionable +proposals: defects with a known root cause, design proposals awaiting +go/no-go, or scoped enhancements queued for future implementation. + +## Convention + +- **Filename:** `docs/ticket-NNNNNN-.md`. The ID is a six-digit + zero-padded integer; the slug is hyphen-lowercase and short enough + to stay readable on a 100-column terminal. +- **Numbering:** monotonic, never reused. Pick the next free integer + greater than every existing ticket. The current next ID is on the + `Next ID` line below; bump it when you open a ticket and commit + the bump in the same commit as the new ticket file. +- **Header:** every ticket starts with + ``` + # Ticket #NNNNNN — + + **Status:** open · awaiting go/no-go (or "in progress", "closed") + **Opened:** YYYY-MM-DD + **Scope:** + **Audience:** + **Hard constraint:** + ``` +- **Body:** problem statement, design choices with trade-offs, + recommendation, implementation sketch, scope boundaries, status. + See `ticket-000001-retrieval-keywords-audit-gap.md` for a worked + template. +- **Closure:** when a ticket lands, flip Status to `closed · landed in + commit ` and leave the file in place. Do not delete tickets; + they are the design log. + +## Distinction from other docs + +`docs/` also contains architecture references and bench journey notes +that are NOT tickets — they describe state of the world rather than +proposing change. Examples that stay un-numbered: + +- `cti-architecture.md` (architecture reference) +- `mesh.md`, `mesh-deploy.md` (architecture + ops reference) +- `naming-deferral.md` (naming convention reference) +- `qa-modes-bench-2026-04-30.md` (point-in-time bench journal) +- `verifier-semantic-gap-design.md`, + `self-reference-thought-chains-design.md` (older design docs that + pre-date the ticket convention; leave as-is unless retroactively + promoting one to a ticket adds value) + +If a doc proposes change AND awaits a decision AND has scoped +implementation cost, it's a ticket. Otherwise it's reference. + +## Index + +Newest first. Update on every open/close. + +| ID | Title | Status | Opened | +|----------|------------------------------------------------|---------|------------| +| #000001 | Retrieval-keywords audit gap | open | 2026-05-01 | + +## Next ID + +`000002` diff --git a/docs/retrieval-keywords-audit-gap.md b/docs/ticket-000001-retrieval-keywords-audit-gap.md similarity index 98% rename from docs/retrieval-keywords-audit-gap.md rename to docs/ticket-000001-retrieval-keywords-audit-gap.md index 6489f7e..bc3baa9 100644 --- a/docs/retrieval-keywords-audit-gap.md +++ b/docs/ticket-000001-retrieval-keywords-audit-gap.md @@ -1,6 +1,7 @@ -# Retrieval-keywords audit gap — close the provenance loop on operator hints +# Ticket #000001 — Retrieval-keywords audit gap -**Date:** 2026-05-01 +**Status:** open · awaiting go/no-go +**Opened:** 2026-05-01 **Scope:** Design proposal for capturing the `--retrieval-keywords` operator hint in the v9.8 audit chain so retrieval is fully reproducible from a providence record alone. Doc-only — no code in this commit.