feat(gatorwalk-factory): a built-in tracker core that the Lab and Linear adapters build on (swamp-club #2794) #391

Merged

seth merged 3 commits from cue/2794-gatorwalk-factory-built into main 2026-09-30 19:27:18 +00:00

Conversation 0 Commits 3 Files changed 28 +2250 -204

seth commented 2026-09-30 19:09:15 +00:00

Owner

Copy link

Closes swamp-club #2794 (https://swamp-club.com/lab/2794).

What

Every project now has a tracker, even one with no external tracker.

• Built-in tracker. @swamp/gatorwalk-factory/tracker keeps tickets in swamp data, with no network calls.
  • Ids are lowercase <prefix>-<slug>-<rnd>, following the work-item key rules. There is no counter.
  • Statuses are the instance's own list (default open, in_progress, shipped, closed), and a ticket can move between any two.
  • Types are the instance's own list (default bug, feature, security).
  • It has the history capability, so publish writes lifecycle entries and the type to it.
• Core contract. The adapter contract gains:
  • create;
  • an explicit capabilities object, where a missing capability is refused as TrackerError invalid and names the capability;
  • an origin on the adapter. issue-<id> records are now origin: snapshot (an external tracker's last read) or origin: builtin (the ticket itself). A read never overwrites a built-in ticket.
• Lab create. Posts to POST /api/v1/lab/issues and builds the result from the reply, so there is no read-back that could invite a duplicate retry.
• Linear create. Files the issue in a configured teamId. Linear has no issue type, so a types argument maps each type to a label, looked up by name. An unmapped type is refused.
• Claim keys. A claimed key no longer starts with the factory definition name.
  • External tickets get <display id>-<slug>-<rnd>, for example 2631-lab-adapter-r2ne.
  • A built-in ticket's first work item takes the ticket's id as its key.
  • A title with no ASCII letters falls back to <lead>-<rnd>.
• Conformance. One suite now runs against all three backends. It covers create, capability refusal, and the new key shapes.
• Tests on the real engine. An integration test drives the built-in tracker through create → claim → start → publish in entry mode → re-claim.
• Docs. DESIGN.md ("The built-in tracker", create, capabilities, origins, keys, and a decision-log entry), the README, and the driving skill are updated.

prefix, statuses, types, and Linear's teamId/types stay tracker-instance arguments until #2795 moves them into the factory definition.

Verification

• Commit dda332559c, attestation 0af02c91: 12 steps passed, 2 skipped (by their guards), 0 failed.
• Both code-review and adversarial-review passed.
• An earlier review round found a real regression: titles with no ASCII letters could not be claimed. It is fixed in this commit, and Linear's label lookup is now filtered by name.
• The remaining non-blocking medium finding (the built-in create checks for a free id and then writes, which could collide on a shared datastore) will be filed as a follow-up.
• Locally, 518 unit tests and 27 integration tests pass.

🤖 Generated with Claude Code

Closes swamp-club #2794 (https://swamp-club.com/lab/2794). ## What Every project now has a tracker, even one with no external tracker. - **Built-in tracker.** `@swamp/gatorwalk-factory/tracker` keeps tickets in swamp data, with no network calls. - Ids are lowercase `<prefix>-<slug>-<rnd>`, following the work-item key rules. There is no counter. - Statuses are the instance's own list (default `open`, `in_progress`, `shipped`, `closed`), and a ticket can move between any two. - Types are the instance's own list (default `bug`, `feature`, `security`). - It has the history capability, so `publish` writes lifecycle entries and the type to it. - **Core contract.** The adapter contract gains: - `create`; - an explicit `capabilities` object, where a missing capability is refused as `TrackerError invalid` and names the capability; - an `origin` on the adapter. `issue-<id>` records are now `origin: snapshot` (an external tracker's last read) or `origin: builtin` (the ticket itself). A read never overwrites a built-in ticket. - **Lab `create`.** Posts to `POST /api/v1/lab/issues` and builds the result from the reply, so there is no read-back that could invite a duplicate retry. - **Linear `create`.** Files the issue in a configured `teamId`. Linear has no issue type, so a `types` argument maps each type to a label, looked up by name. An unmapped type is refused. - **Claim keys.** A claimed key no longer starts with the factory definition name. - External tickets get `<display id>-<slug>-<rnd>`, for example `2631-lab-adapter-r2ne`. - A built-in ticket's first work item takes the ticket's id as its key. - A title with no ASCII letters falls back to `<lead>-<rnd>`. - **Conformance.** One suite now runs against all three backends. It covers `create`, capability refusal, and the new key shapes. - **Tests on the real engine.** An integration test drives the built-in tracker through create → claim → start → publish in entry mode → re-claim. - **Docs.** DESIGN.md ("The built-in tracker", create, capabilities, origins, keys, and a decision-log entry), the README, and the driving skill are updated. `prefix`, `statuses`, `types`, and Linear's `teamId`/`types` stay tracker-instance arguments until #2795 moves them into the factory definition. ## Verification - Commit dda332559c5b, attestation 0af02c91: 12 steps passed, 2 skipped (by their guards), 0 failed. - Both code-review and adversarial-review passed. - An earlier review round found a real regression: titles with no ASCII letters could not be claimed. It is fixed in this commit, and Linear's label lookup is now filtered by name. - The remaining non-blocking medium finding (the built-in create checks for a free id and then writes, which could collide on a shared datastore) will be filed as a follow-up. - Locally, 518 unit tests and 27 integration tests pass. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

seth added 1 commit 2026-09-30 19:09:15 +00:00

feat(gatorwalk-factory): a built-in tracker core that the Lab and Linear adapters build on (swamp-club #2794) ... dda332559c

Every project now has a tracker. @swamp/gatorwalk-factory/tracker keeps
tickets in swamp data, with lowercase <prefix>-<slug>-<rnd> ids and no
counter, the instance's own statuses (open, in_progress, shipped, closed by
default, moving in any direction) and types, and the history capability.

The adapter contract gains create, an explicit capabilities object (a
missing capability is refused as invalid, naming it) and an origin;
issue-<id> records carry origin builtin or snapshot, and only snapshots are
rewritten by a read. The Lab files an issue through POST /api/v1/lab/issues;
Linear files in a configured teamId and labels the type through a types map.
Claimed keys drop the factory definition name: <display id>-<slug>-<rnd>,
and a built-in ticket's first work item takes the ticket's id. One
conformance suite runs against all three backends, and an integration test
drives the built-in tracker end to end on the real engine.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

seth added 2 commits 2026-09-30 19:24:26 +00:00

Merge remote-tracking branch 'origin/main' into cue/2794-gatorwalk-factory-built ... 93a8b0066b

# Conflicts:
#	gatorwalk-factory/DESIGN.md

Merge remote-tracking branch 'origin/main' into cue/2794-gatorwalk-factory-built f5a450d2ce

seth merged commit 9d0711be8f into main 2026-09-30 19:27:18 +00:00

seth deleted branch cue/2794-gatorwalk-factory-built 2026-09-30 19:27:19 +00:00

seth referenced this pull request from a commit 2026-09-30 19:27:19 +00:00

feat(gatorwalk-factory): a built-in tracker core that the Lab and Linear adapters build on (swamp-club #2794) (#391)

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

swamp-club/swamp-extensions!391

No description provided.