Tickets and issues

neosource carries two kinds of work item on one storage row, and which one you are looking at is decided by a single field: whether it belongs to a repo.

	Ticket	Issue
Addressed	`ENG-7`	`acme/api#1526`
Scoped to	a team	a repo
Numbered by	the team’s sequence	the repo’s sequence
Filed by	people on the team	anyone who can see the repo
Command group	`neo ticket`	`neo issue`

A ticket is planning work. It lives on a team’s board, it is numbered KEY-N from that team’s own sequence, and it has no repo at all — which is the point, because the work it describes usually spans several, or none yet.

An issue is intake. It belongs to one repository, it is numbered from that repository’s sequence, and it is what an outside reporter, a crash handler or a bot files when something is wrong with that specific codebase.

Neither is a lesser form of the other, and neither converts into the other. A repo issue is a real report against a real repo; a ticket is the planning work someone decided to do about it. Collapsing them would either force every report to pick a team it has no way of knowing, or force every planning item to pretend it belongs to one repo.

Tracks joins them

The link between the two tracks is a tracks relationship, and it has a fixed direction: a ticket tracks an issue, never the reverse.

ENG-7  ──tracks──▶  acme/api#1526
       ◀─tracked_by─

neo ticket track writes it; the inverse tracked_by row is written by the server in the same transaction, so the relationship reads correctly from either end and is never half-present. You cannot create a tracked_by row directly, and you cannot point tracks from an issue at a ticket — the server refuses both.

neo ticket track ENG-7 acme/api#1526
neo ticket untrack ENG-7 acme/api#1526

One ticket may track many issues, which is the usual shape: three bug reports across two repos, one piece of planned work that resolves them.

The two command groups

Every neo ticket verb has a neo issue twin, and they run the same code — neo ticket is the team-scoped path with the team supplied by the reference itself rather than by a flag.

Ticket	Issue
`neo ticket list --team ENG`	`neo issue list acme/api`
`neo ticket create --team ENG --title …`	`neo issue create acme/api --title …`
`neo ticket view ENG-7`	`neo issue view 1526 acme/api`
`neo ticket claim ENG-7`	`neo issue claim 1526 acme/api`

neo ticket’s numbered verbs take no team flag and no repo target, because ENG-7 already says which board it is on. Where the team lives in a non-personal workspace, qualify it: neo ticket view acme/ENG-7.

The numbered neo issue verbs accept both spellings. A bare number is scoped by the repo target or --team exactly as it always was, and a KEY-N reference carries its own team, so it combines with neither:

neo issue view 1526 acme/api    # repo-scoped, by target
neo issue view 7 --team ENG     # team-scoped, by flag
neo issue view ENG-7            # team-scoped, by reference

neo ticket list shows the team’s board, which is its tickets — every row renders KEY-N. A repo-bound issue never appears there even when it carries the same team; it lives on its repo’s list (neo issue list <owner>/<repo>, rendering owner/repo#N), and the way a team plans one is to file a ticket that tracks it.