docs: formalize ticket convention; rename retrieval-keywords gap to #000001

Tickets are flat docs/ticket-NNNNNN-<slug>.md — actionable proposals
awaiting go/no-go, scoped defects, or queued enhancements.
Architecture references and bench journals stay un-numbered.

docs/TICKETS.md: index + convention + Next ID line so future shifts
know where the next number comes from. Renumbering protocol: every
new ticket commit bumps the Next ID line atomically with the new
ticket file. Status field tracks open / in progress / closed; closed
tickets keep the file in place as a design log.

docs/ticket-000001-retrieval-keywords-audit-gap.md: the ticket
opened in 73058b0, renamed and re-headered to fit the convention.
This commit is contained in:
russell@unturf.com 2026-05-01 12:09:00 -04:00
parent 73058b0e66
commit b189f4bee3
No known key found for this signature in database
2 changed files with 65 additions and 2 deletions

62
docs/TICKETS.md Normal file
View file

@ -0,0 +1,62 @@
# Aborist tickets — index
Aborist uses a flat `ticket-NNNNNN-<slug>.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-<slug>.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<short title>
**Status:** open · awaiting go/no-go (or "in progress", "closed")
**Opened:** YYYY-MM-DD
**Scope:** <one-liner what this ticket is for>
**Audience:** <who reads this>
**Hard constraint:** <invariants this ticket commits to NOT break>
```
- **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 <sha>` 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`

View file

@ -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.