Unify ticket ID extraction across `get-ticket-id` and `get-session-context`

[williamthorsen]

Problem

The get-ticket-id skill (Bash script) and the get-session-context skill (zero-Bash inline spec) implement parallel ticket-ID extraction logic that diverges on multiple axes:

• Case sensitivity: get-ticket-id matches [A-Z]+-[0-9]+ (case-sensitive); get-session-context matches case-insensitively and uppercase-normalizes.
• Author/scope prefixes: get-ticket-id matches anywhere in the branch (so wt/COMPPLAN-795 → COMPPLAN-795); get-session-context is start-anchored and explicitly returns null for author-prefixed branches.
• Sub-ticket suffix .N: both skills currently capture .N as part of the ID, but .N has no semantic meaning (it doesn't correspond to a real Jira reference) and has never been used in this project's branches.

Two skills purporting to extract "the ticket ID from a branch name" can disagree on the same input. Most visibly: lowercase project keys (wt/mac-130) yield divergent results.

Context

ticket_id is consumed by both skills' downstream callers — artifact path namespacing, PR rendering, external ticket lookups. Inconsistent extraction means callers can see different IDs depending on which skill they invoke.

.N capture is vestigial — it has been in the regex since the initial agents-workspace commit (CODY-46) without documented design intent and is not used in any branch. Jira has no decimal-sub-ticket concept, so .N IDs cannot be looked up externally; preserving them only causes downstream lookups to fail.

Solution

Establish a single canonical extraction contract, documented in a shared spec file that both skills cite. Update both implementations to match.

Canonical contract:

• Pattern (case-insensitive): [A-Za-z]{2,}-[0-9]+ — first occurrence anywhere in the branch name wins.
• Output: uppercased.
• Trailing .N (sub-ticket) and -description suffixes are tolerated in input but not part of the canonical ID. The greedy-digit regex naturally stops at . and -letter boundaries.

Behavior table:

Input	Output
MAC-130	MAC-130
mac-130	MAC-130
wt/compPlaN-795	COMPPLAN-795
wthorsen/MAC-130	MAC-130
wt/jira-123.1-some-suffix	JIRA-123
jira-123-1	JIRA-123
MAC-147-some-description	MAC-147
feat-2	FEAT-2
feat/foo-2	FOO-2
main	(empty)

Files affected:

• packages/agents/content/skills/_data/ticket-id-extraction.md (new): canonical spec
• packages/agents/content/scripts/get-ticket-id.sh: regex update in extract_jira_id
• packages/agents/content/skills/get-ticket-id/SKILL.md: cite spec; update commit-message extraction snippet
• packages/agents/content/skills/get-session-context/SKILL.md: relax start-anchor; drop .N; remove "author-prefixed branches return null" constraint and edge case; update worked example 6; add author-prefixed worked example; cite spec
• packages/agents/content/scripts/__tests__/get_ticket_id_test.sh: invert/replace tests that assumed case-sensitivity or .N preservation; add positive coverage

The extract_bare_number fallback and ticket_ref_prefix handling in get-ticket-id.sh are unchanged — those serve #-style projects and are orthogonal to the Jira-style alignment.

Acceptance criteria

• All inputs in the behavior table produce the listed outputs from get-ticket-id.sh.
• The same inputs produce the same outputs when extracted per the updated get-session-context spec.
• _data/ticket-id-extraction.md exists and is the single source of truth; both get-ticket-id/SKILL.md and get-session-context/SKILL.md cite it.
• get-session-context/SKILL.md no longer states that author-prefixed branches return null.
• New and modified behavior in this change is covered by tests, including lowercase input, mixed-case input, multi-character author prefixes, sub-ticket suffix dropping, and description suffix tolerance.

[williamthorsen]

Insights from the unification work (run 20260504-152352Z)

I1 — Drift in dual-implementation contracts

The two skills had drifted along three independent axes — case sensitivity, anchoring, and .N suffix capture — and each axis traced back to a different historical decision. Case-sensitivity came from the original Bash regex (CODY-46). Start-anchoring came from the zero-Bash spec written later. .N capture came from the original regex without documented design intent.

The shared spec at _data/ticket-id-extraction.md is the right architectural fix, but the drift pattern is generalizable: any contract that lives in two implementations will eventually disagree without a citable single source of truth. A future enhancement worth considering is a test harness that exercises both the Bash script and a zero-Bash trace against the same fixture table — that would catch silent re-divergence in CI.

I2 — feat-2 → FEAT-2 and the load-bearingness of ticket_id

The behavior-table cases feat-2 → FEAT-2 and feat/foo-2 → FOO-2 follow from the unanchored, low-letter-bound contract, and the spec calls them out — but they are surprising in isolation. Downstream callers that consume ticket_id may now match branches whose authors did not intend a Jira reference.

This is acceptable as long as ticket_id is treated as informational (e.g., for artifact namespacing and PR rendering, where a non-empty value is harmless). It becomes a problem if any caller treats ticket_id as load-bearing — for example, attempting to look up FEAT-2 in Jira would fail. Worth a future audit of ticket_id consumers if a regression is reported.

S2 follow-up

The drive-by commit (88c7c97) added a note to the immutability contract section of get-session-context/SKILL.md clarifying that extraction-logic changes don't trigger manifest re-derivation. Any worktrees on wt/... or *.N branches that pre-date this PR will retain stale ticket_id values until the affected .agents/*.branch-manifest.json files are deleted manually.