Beagle SCM

Tickets

For LLM-heavy development, a machine-writable, machine-readable ticket format is necessary to organize the process. Tickets must track an issue as it is encountered/develops, a tally of open tickets must be kept.

• Ticket pages are stored as todo/TOPIC/TOPIC-123.mkd or todo/TOPIC/TOPIC-123/README.mkd (for bigger ones).
• Ticket documents follow the wiki conventions, including the line budget and greppability (no line wrap); e.g. grep '^# ' todo/GET/*.mkd produces all page headers.
• Closed tickets/topics must be delisted from parents.
• Corroborating evidence files (logs, screenshots may accompany tickets).
• Section layout for tickets is stricter.
• Crosslinking between tickets, wiki and other pages is encouraged.
• A spec-code discrepancy or a bug found mid-fix becomes its OWN ticket, link both ways.
• Comments to code changes may mention a ticket, preferably in the budget of 2 lines.
• The ticket header starts with the code ABC-123: title
• Ticket meta goes in Key: value meta pairs (StrictMark) directly under the header, each key at most once; registered keys:
  1. Who: assignee; a claim is a commit, authored+dated for free
  2. Due: hard deadline, yyyy-mm-dd
  3. For: target milestone or release
  4. Ask: reporter, when not the ticket's committer
  5. Env: environment the issue manifests in
  6. Rev: found-in revision, a URI#hashlet
  7. Dup: duplicate-of / superseded-by ticket
  8. Sub: parent ticket, for ticket families
  9. Now: status OPEN, DONE, DONT, STALE etc
  10. Sev: severity of an open ticket: CRIT HIGH MED LOW
  11. On1: On2: … builds on / depends on, one ticket code per slot;
  12. See: related ticket; symmetric, one side suffices
  13. Rep: the repo the ticket relates to, a repo URI, most likely relative (///be, ///jab), official URIs work too
  14. Vox: hand written by (no AI)
• Never store what the log derives: opened/closed who+when come from jab log | grep TKT-123.
• Each section carries a one-line header, a short summary, and a few bulletpoints.
• Line-budget is counted in 64-char lines:
  1. header 1 line,
  2. top intro 8 lines,
  3. section intro 4,
  4. bulletpoint 2,
  5. nested bulletpoint 1 line.

File layout

Tickets are grouped into topics. Tickets from different topics would safely parallelize in most cases. Fat tickets with additional/attached files files get directory layout, one-shotters stay single-file.

• Thin tickets todo/TOPIC/TOPIC-123.mkd.
• Fat tickets todo/TOPIC/TOPIC-123/README.mkd.
• Attached files must be linked from README.mkd.
• Topics most often correspond to subsystems.
• todo/README.mkd and todo/TOPIC/README.mkd are both retired; we use grep to list tickets;
• Concurrent users may book ticket number ranges, e.g. ANY-3?? or POST-4??, marked in todo/README.mkd or todo/TOPIC/README.mkd (Section "Sessions", bulletpoints).
• Concurrent page edits are probably resolved by SCM.

Section structure

Ticket page section structure is fixed. Any volumous texts (logs, chats, related docs) must be kept as separate files, any related pages linked. Sections that are exclusively human-editable get marked with Hand written under the title or with -- John A. Smith if single-author (indent 4 spaces). Request the user to edit those.

• ## Input sections:
  1. ### Context: the use case, currently blocked work, incident evidence like logs or chat excepts.
  2. ### Goals: feature to implement, problem to solve, bug to fix, limits to fit under, tests to make pass.
  3. ### Constraints: resource limitations, APIs to use, LoC budget, time/tockens to spend, etc.
• The ## WIP sections:
  1. ### Design decisions.
  2. ### TODOs, linked and sub-tickets (a -[ ] TODO list, marked once done [v], blocked [-] wontfix/moot [x]). TODOs may nest (respect the line budget).
  3. ### Blockers and bummers.
• ## Outcome: mentions the hashlets of landed commits (bulletpoints), cancelled parts (bulletpoints).