From b189f4bee34c5afe8cd5e70c8436eb5c277be25e Mon Sep 17 00:00:00 2001
From: "russell@unturf.com" <russell@unturf.com>
Date: Fri, 1 May 2026 12:09:00 -0400
Subject: [PATCH] docs: formalize ticket convention; rename retrieval-keywords
 gap to #000001
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 docs/TICKETS.md                               | 62 +++++++++++++++++++
 ...et-000001-retrieval-keywords-audit-gap.md} |  5 +-
 2 files changed, 65 insertions(+), 2 deletions(-)
 create mode 100644 docs/TICKETS.md
 rename docs/{retrieval-keywords-audit-gap.md => ticket-000001-retrieval-keywords-audit-gap.md} (98%)

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