#2966 stagecraft: short work-item ids: a tracker prefix plus a counter (blog-12), the ticket's id for external trackers (abc-12), and -2 for later work on the same ticket

Replace stagecraft's long work-item keys with short, sayable ids. On the built-in tracker that's a configurable prefix plus a counter (blog-12). With external trackers it's the ticket's own id (abc-12). A second work item on the same ticket adds a sequence number (abc-12-2).

Why

Keys today follow #2744: <factory definition>-<whole title slug>-<4 random chars>, kept up to swamp's 64-character name limit. Built-in tracker ticket ids use the same pattern (DESIGN.md, "Keys are stagecraft's" and "The built-in tracker"). A real one, from Seth's demo, is blog-using-stagecraft-organizing-shipping-blog-posts-6r6t. It's too long to say, type or display. It broke the studio Board (#2963), and it mostly repeats the title, which every view already shows. Seth (2026-10-02): "I'm worried they are too long and bad ux."

#2744 rejected sequences (cue-7) for three reasons, and none still holds:

• "Needs one counter minted in one place." The built-in tracker (#2794) is that place. Its create runs under swamp's per-model lock (the reason #2832 was closed), so a counter there can't race.
• "Reuses numbers when a factory is recreated." Start the counter above the highest number already recorded.
• "Reads like a tracker id." On the built-in tracker the work item is the ticket, so that's the point.

Decided by Seth (2026-10-02)

• Built-in tracker: <prefix>-<n>, for example blog-12. n is a per-tracker-instance counter starting at 1.
• External trackers: the ticket's own id. Linear's ABC-12 becomes abc-12. A tracker whose ids are bare numbers (the swamp-club Lab's #2711) uses the instance's prefix: lab-2711, or whatever the instance's prefix is.
• A second or later work item on the same ticket appends a sequence: abc-12-2, abc-12-3. The first has no suffix.
• The prefix is configurable on the tracker instance, a global argument on the built-in, Linear and swamp-club tracker models. It's not on the factory, since a factory names its tracker (#2795).

Scope

• Minting. The built-in tracker's create takes the next number under its lock and persists the counter in the tracker's own data. The counter starts above the highest number found among existing tickets and work items for that prefix, so recreating a tracker never reuses an id. The ticket id and the first work item's key are the same string.

• claim. For an external ticket, claim derives the key from the ticket id: lowercased, with characters outside [a-z0-9-] mapped to -. If any work item already exists for that ticket (the ticket index, _lib/tracker/core/claim.ts), it appends -<n>.

• new_key (a work item with no ticket). Decide during planning:

  • (a) It always creates a built-in ticket first, so every work item has a ticket and a counter id.
  • (b) It mints from the factory's tracker counter without creating a ticket.
  • (c) It is removed or renamed, if (a) makes it redundant.

  Say what start does when given a key by hand; today it accepts any unused name.

• The prefix.

  • Validation: it must match swamp's instance-name rules once combined with a number (^[a-z0-9][a-z0-9_-]*$, 64 characters at most), and it should be short; set a sensible maximum, for example 12.
  • Default when unset: decide one, for example the tracker instance's name, cut down.
  • Uniqueness: two tracker instances in one repo with the same prefix would collide. validate, or the tracker's own check (#2847, if it has landed), should refuse that.
  • Changing it later: decide what happens. Existing keys never change, so a new prefix only affects new ids.

• Titles carry meaning now. Keys no longer describe the work, so every place that shows a key to a person also shows the title:

  • status output and the summary report;
  • the skill's examples;
  • the studio, where #2963 (in progress) makes the title the Board card headline, and #2944, the work-item view, does likewise.

  Check that nothing else depends on the slug being in the key.

• Docs. In DESIGN.md, rewrite "Keys are stagecraft's" and the built-in tracker id rules, and add a decision-log entry that replaces #2744's and records the reasons above. Update the README, the skill (driving, authoring, getting started) and the examples wherever a key appears.

• No migration. No keys exist outside demo repos before go-live. Records under the old key style aren't rewritten, but they must still be readable. A key is just a model name, so old work items keep working.

Done when

• A built-in tracker with prefix: blog mints blog-1, blog-2 and so on. Recreating it continues above the highest number.
• Claiming Linear ABC-12 gives abc-12, and claiming it again gives abc-12-2.
• A Lab-style numeric ticket gives <prefix>-2711.
• Duplicate prefixes in one repo are refused with a clear message.
• Tests cover the counter, collisions, recreation, and the claim derivation for both id styles.
• The docs and examples show the new form.

Running alongside: #2963 (Board overflow; keep its truncation as a backstop), #2944 (work-item view), #2947 (publication prep) and #2949 (swamp core). Rebase onto origin/main before the PR.