Relationships
#2744 gatorwalk-factory: work-item keys are a title slug plus a short random suffix
Opened by skunk-ape · 9/29/2026· Shipped 9/30/2026
Part of the gatorwalk-factory rebuild (gatorwalk-factory/ in swamp-extensions). Read DESIGN.md, "The model types" ("Keys are gatorwalk's"), first.
Problem
new_key generates <lifecycle>-<8 random base32 characters>, for example cue-k3x9m2qa (generateKey in _lib/work_item_ops.ts). A key is how a person refers to a work item everywhere: in status, the summary report, commands and conversation. A random key tells them nothing about the work.
Decision (Seth)
Keys become a slug of the work's title plus a short random suffix: <lifecycle>-<slug>-<suffix>, for example cue-add-json-output-k3.
- Why not sequential (
cue-7): it needs a counter minted in one place, it resets or reuses numbers when a holder is recreated, and it reads like a tracker id. - Why not calver: it is long, hard to say, and repeats what the journal records.
- Ordering does not matter. Work is often deferred and picked up out of order.
- The slug is immutable, like any key. If the work changes meaning, the key stays as it is. A person can abandon the item and start a new one when that matters. This is accepted.
- From a tracker, the slug starts with the ticket's display id, then its title:
swamp-extensions-2734-drive-lab-issue-k3. The ticket id in the slug is for reading only.externalRefsstays the only link the code uses, and a Linear identifier that changes when an issue moves team leaves the slug stale, which is accepted too.
Scope
new_keytakes a requiredtitleinput and returns<lifecycle>-<slug>-<suffix>.- The slug is lowercase ASCII words joined by
-, with other characters dropped, collapsed and trimmed. - It is truncated at a word boundary so the whole key fits swamp's 64-character instance-name limit. Check the actual name rules swamp enforces, and cite them.
- The suffix is short random base32. Choose the length and justify it; the existing free-name check (
freshKey) retries on a collision. - A title with nothing sluggable left is refused with a clear message.
- The lifecycle-name prefix stays.
- The slug is lowercase ASCII words joined by
claim(GW-18,_lib/claim.ts) builds its reserved key the same way, from the ticket's display id and title.startstill accepts any unused name, so a person can choose a key by hand.- Update the skill (
SKILL.md,references/driving.md, the worked example), README and DESIGN.integration/skill_test.tsmust still run the worked example as written.
Done when
- Unit tests cover:
- the slug rules: punctuation, unicode, empty after slugging, very long titles, and word-boundary truncation;
- the 64-character limit with a long lifecycle name;
- the collision retry;
claim's key for both the Lab and Linear adapters.
- The integration suite passes on the real engine.
Out of scope
- A stored, mutable title on the work item.
- Renaming existing work items. Nothing is published, so there is nothing to migrate.
Sequencing
#2734 is editing claim.ts (its guard against issues that issue-lifecycle already drives). Do the new_key part first, and rebase before changing claim.
Shipped
Click a lifecycle step above to view its details.
system commented 9/29/2026, 10:44:01 PM
Classified automatically when this issue was filed.
- Source: Extensions
If you feel this classification is incorrect, add a ripple to tell us so.
Sign in to post a ripple.