Repository navigation
issue list and watch: --project and --milestone by id, never a silent empty or mixed list - #8
Merged
Merged
Conversation
project_filter reads a URL, slugId, UUID or name into a ProjectFilter, and the NOT_FOUND / AMBIGUOUS decision over what it found becomes one_project. Both are public so issue list and watch can read --project the same way; project show and update behave as before.
--project went to Linear as a project name, so the UUID, slugId or URL that project list and project show hand out matched nothing and listed no issues with exit 0, and a name two projects share listed the issues of both. --milestone had the same two failures, across projects. Both are now looked up first, together in one request (PlaceResolve), and the issue filter is by id. --project takes what project show takes: a linear.app project URL, a slugId, a UUID or a name (ignoring case). --milestone takes a UUID or a name, looked for in the --project project when both are given. A reference that finds nothing is NOT_FOUND and a name that finds several is AMBIGUOUS with candidates, each with kind and name, as the rest of linearctl reports names. none still means "in no project/milestone" and costs no request; --milestone NAME with --project none is a usage error, since a milestone is a project's. watch shares the filter, so it resolves them once, before its snapshot.
Linear repeats names: milestone names across projects, and project names too. The demo had neither, so --project and --milestone could show only their happy path there. Checkout v2 now has Beta and GA, Mobile 3.0 a Beta of its own, a few issues sit in them, and a completed "Platform Reliability" shares its name (ignoring case) with the planned one. The golden outputs that list those issues, projects and milestones are re-recorded; nothing else changes.
From the demo workspace: a project by slugId, UUID, URL and name; one that matches nothing, and a name two projects share; none; a milestone by id, by name within a project, a name two projects' milestones share, and one the project does not have; --milestone with --project none; and watch failing the same way before it streams.
The README, docs/design.md and AGENTS.md (and so the skill) said --project takes a name. They now say which references it takes, that both flags are resolved to ids in one request before listing, and how a reference that finds nothing or several things fails. CHANGELOG entry under Unreleased.
The lookup's own failure (a Linear error) ends issue list with LINEAR_ERROR before IssueList is sent; it was the one new line no test reached.
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues are reported for the project and milestone reference-resolution changes.
No open issues 🎉
What changed in this PR
This PR makes project and milestone filtering in linearctl issue list and watch resolve references to unique IDs before reading issues, preventing silent empty results or results mixed across same-named projects.
Changes:
- Reuses project reference parsing and adds a shared lookup with explicit
NOT_FOUNDandAMBIGUOUSerrors. - Adds milestone and duplicate-name demo data, acceptance tests, and golden cases.
- Updates command help, documentation, and generated skill references.
| File | Description |
|---|---|
tests/golden/expected/0419-watch-project-checkout-v2-milestone-Launch-json.txt |
Covers missing milestone in watch. |
tests/golden/expected/0418-watch-project-platform-reliability-json.txt |
Covers ambiguous project in watch. |
tests/golden/expected/0417-watch-project-Nope-json.txt |
Covers unknown project in watch. |
tests/golden/expected/0416-issue-list-project-none-milestone-Beta-json.txt |
Covers incompatible project/milestone flags. |
tests/golden/expected/0415-issue-list-project-Mobile-3-0-milestone-GA-json.txt |
Covers milestone outside the selected project. |
tests/golden/expected/0414-issue-list-milestone-beta.txt |
Covers text milestone ambiguity errors. |
tests/golden/expected/0413-issue-list-milestone-beta-json.txt |
Covers structured milestone ambiguity errors. |
tests/golden/expected/0412-issue-list-project-checkout-v2-milestone-BETA.txt |
Covers case-insensitive scoped milestone lookup. |
tests/golden/expected/0411-issue-list-project-Mobile-3-0-milestone-beta-fields-identifier-project-projectMi.txt |
Covers project-scoped milestone results. |
tests/golden/expected/0410-issue-list-milestone-ac0845c6-4c40-5517-86b9-d0c03f1e50d0-fields-identifier-proj.txt |
Covers milestone UUID filtering. |
tests/golden/expected/0409-issue-list-project-none-fields-identifier-project-json.txt |
Covers issues without a project. |
tests/golden/expected/0408-issue-list-project-9dd21914662d.txt |
Covers project disambiguation by slugId. |
tests/golden/expected/0407-issue-list-project-platform-reliability.txt |
Covers text project ambiguity errors. |
tests/golden/expected/0406-issue-list-project-platform-reliability-json.txt |
Covers structured project ambiguity errors. |
tests/golden/expected/0405-issue-list-project-Nope.txt |
Covers text unknown-project errors. |
tests/golden/expected/0404-issue-list-project-Nope-json.txt |
Covers structured unknown-project errors. |
tests/golden/expected/0403-issue-list-project-https-linear-app-northwind-issue-ENG-142-json.txt |
Covers rejection of non-project URLs. |
tests/golden/expected/0402-issue-list-project-https-linear-app-northwind-project-checkout-v2-baac88349ee8-o.txt |
Covers project URL filtering. |
tests/golden/expected/0401-issue-list-project-5DC3E15C-4273-5511-8167-BAAC88349EE8-fields-identifier-projec.txt |
Covers uppercase project UUID input. |
tests/golden/expected/0400-issue-list-project-baac88349ee8-fields-identifier-project-projectMilestone-json.txt |
Covers project slugId filtering. |
tests/golden/expected/0398-issue-list-view-checkout-bugs-json.txt |
Reflects milestones in saved-view results. |
tests/golden/expected/0384-complete-issue-list.txt |
Updates completion descriptions. |
tests/golden/expected/0361-issue-show-ENG-142-demo-json.txt |
Reflects the issue’s demo milestone. |
tests/golden/expected/0360-issue-list-demo-json.txt |
Reflects demo milestone assignments. |
tests/golden/expected/0308-project-show-checkout-v2-issues-0-json.txt |
Includes project milestone metadata. |
tests/golden/expected/0306-project-show-Checkout-v2-json.txt |
Includes milestones in project details and issues. |
tests/golden/expected/0299-milestone-list.txt |
Adds text demo milestone output. |
tests/golden/expected/0298-milestone-list-json.txt |
Adds JSON demo milestone output. |
tests/golden/expected/0295-project-list.txt |
Includes the second similarly named project. |
tests/golden/expected/0294-project-list-json.txt |
Includes the additional project’s metadata. |
tests/golden/expected/0272-issue-show-ENG-142-comments-json.txt |
Reflects milestone data alongside comments. |
tests/golden/expected/0268-issue-show-https-linear-app-northwind-issue-ENG-143-x-json.txt |
Reflects the GA milestone. |
tests/golden/expected/0262-issue-view-eng-142-comments-0-json.txt |
Reflects milestone data without comments. |
tests/golden/expected/0260-issue-show-ENG-142-json.txt |
Reflects the Beta milestone. |
tests/golden/expected/0249-issue-list-milestone-none.txt |
Excludes newly assigned milestone issues. |
tests/golden/expected/0240-issue-list-priority-urgent-priority-2-json.txt |
Reflects milestones in priority-filtered results. |
tests/golden/expected/0234-issue-list-id-ENG-142-id-ENG-9999-json.txt |
Reflects milestone data in partial results. |
tests/golden/expected/0232-issue-list-id-eng-142-id-ENG-131-json.txt |
Reflects milestone data in ID lookups. |
tests/golden/expected/0226-issue-list-query-coupon-json.txt |
Reflects milestones in search results. |
tests/golden/expected/0224-issue-list-project-checkout-v2-json.txt |
Reflects milestones in project-filtered results. |
tests/golden/expected/0216-issue-list-state-Todo-json.txt |
Reflects milestones in state-filtered results. |
tests/golden/expected/0212-issue-list-assignee-jonas-northwind-example-json.txt |
Reflects milestones in assignee-filtered results. |
tests/golden/expected/0208-issue-list-assignee-me-json.txt |
Reflects milestones in current-user results. |
tests/golden/expected/0202-issue-list-label-BUG-label-customer-reported-json.txt |
Reflects milestones in combined-label results. |
tests/golden/expected/0200-issue-list-label-bug-limit-0-json.txt |
Reflects milestones in all matching bugs. |
tests/golden/expected/0198-issue-list-limit-5-cursor-c5-json.txt |
Reflects milestone data on subsequent pages. |
tests/golden/expected/0196-issue-list-limit-5-json.txt |
Reflects milestone data on the first page. |
tests/golden/expected/0072-describe.txt |
Updates machine-readable flag descriptions. |
tests/golden/expected/0067-issue-list-help-json.txt |
Updates issue-list help expectations. |
tests/golden/expected/0048-issue-list-h.txt |
Updates short-help invocation output. |
tests/golden/expected/0047-watch-help.txt |
Documents watch’s startup lookup. |
tests/golden/expected/0023-issue-list-help.txt |
Documents accepted references and lookup errors. |
tests/golden/cases.jsonl |
Adds 20 reference-resolution golden cases. |
src/queries.rs |
Adds and registers the combined PlaceResolve query. |
src/demo.rs |
Builds milestones and links them to demo issues. |
src/commands/watch.rs |
Resolves references once before watching. |
src/commands/project.rs |
Exposes shared project parsing and selection helpers. |
src/commands/issue.rs |
Resolves filters to IDs and adds validation tests. |
skills/linearctl/SKILL.md |
Documents supported project and milestone references. |
skills/linearctl/references/watch.md |
Refreshes generated watch documentation. |
skills/linearctl/references/issue.md |
Refreshes generated issue-list documentation. |
README.md |
Explains reference filtering and error behavior. |
docs/design.md |
Records lookup semantics and command syntax. |
demo/workspace.json |
Adds milestones and a similarly named project. |
CHANGELOG.md |
Records filtering fixes and demo changes. |
AGENTS.md |
Updates reference guidance for callers. |
acceptance/places_test.go |
Tests resolution, errors, request order, and watch integration. |
acceptance/milestone_test.go |
Updates expectations to resolved milestone IDs. |
acceptance/issue_test.go |
Removes the superseded project-name filter expectation. |
Review effort: Balanced
find_project keeps main's split, two light matches and one detail, and decides on the matches through one_project, which issue list's --project lookup shares. CHANGELOG's Unreleased holds #7's Added before this branch's Changed and Fixed. The golden cases keep main's 0400-0405 and follow them with this branch's; expected/ is re-recorded.
linyiru
added a commit
that referenced
this pull request
Oct 28, 2026
issue list's long help keeps both: how --project and --milestone are looked up, then what --blocked, --blocking and the relation fields do; the README row names milestone and the relation fields. CHANGELOG's Unreleased has one Changed and one Fixed section, #8's entries before this branch's. The golden cases follow main's with this branch's; expected/ is re-recorded, and issue show's rows carry both the demo's milestones and the relation sides' states.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
issue listandwatchsharelist_filter, which sent--projectto Linear as{"project": {"name": {"eqIgnoreCase": …}}}and--milestoneas{"projectMilestone": {"name": {"eqIgnoreCase": …}}}. A real caller (an issue-tracking wrapper built on linearctl) hit both consequences:project listandproject showhand out matched no project name, so the list was empty with exit 0. Nothing said the reference was wrong.project showalready reads a URL, slugId, UUID or name and reportsAMBIGUOUSwith candidates for a shared name.issue listnow does the same.What
project_filter(URL / slugId / UUID / name →ProjectFilter) andone_project(the NOT_FOUND / AMBIGUOUS decision) inproject.rsbecome public.project showandupdatebehave as before.list_filterstays pure. It writes--projectasproject_filterreads it, and--milestoneas{id}for a UUID or{name: eqIgnoreCase}otherwise, scoped withproject: <the --project filter>when both are given. Thenresolve_placessends one request,PlaceResolve(projectsandprojectMilestones, each behind@include), and replaces both with{id: {eq}}.NOT_FOUNDwithkindandname(and a hint).AMBIGUOUSwithcandidates. A project candidate hasid,nameandslugId; a milestone candidate hasid,nameandproject.nonestill means "in no project / milestone" and sends no request.--milestone NAMEwith--project noneis usage (2).watchcalls the same function once, before its snapshot, and filters by id from then on.issue list/watchlong help, the README,docs/design.md(Inputs), AGENTS.md and the generated skill describe this (a9be209), plus a CHANGELOG[Unreleased]entry.Interface decisions
--project/--milestoneis notnone, including for a UUID or slugId. A UUID could filter without a lookup, but then a mistyped or invisible id would again list nothing with exit 0. One request also checks the milestone against the project. With--cursorpaging, each page repeats the lookup.--milestonetakes a UUID or name, not a URL: milestones have no slugId or URL form in the schema we read.--team. A project can span teams, and scoping would make a name's meaning depend on another flag. A shared name isAMBIGUOUS, and the caller passes the slugId or URL fromcandidates.PlaceResolveasks forfirst: 50, socandidateslists every match up to 50.project showkeepsfirst: 2.--jsonfield names are unchanged.issue create/updatestill resolve--projectby name only (untouched).Tests
places_before_resolvingcheckslist_filterfor UUID, slugId, URL, name andnone, milestone by id, by name, and by name within a project, plus the usage errors (--project none --milestone X, non-project URL, URL without id, control character).documents_match_the_schemacoversPlaceResolve.acceptance/places_test.go, the fake validates every request against the schema):none. Each checks the exactPlaceResolvevariables, that exactlyPlaceResolve,IssueListwere sent, and the id filter.nonesends no lookup.code/kind/name/candidatesand that noIssueListfollows.watchresolves once beforeWatchIDsand snapshots by id;watchwith an unknown project fails NOT_FOUND.TestIssueListFiltersandTestMilestoneFilterAndListare updated for the id filter.none, milestone by id, milestone by name within a project (JSON and text), ambiguous milestone (JSON and text), a milestone not in the project,--project none --milestone, andwatchwith an unknown project, an ambiguous project and an unknown milestone.make check: fmt, clippy, gofmt, go vet, 41 unit + integration, acceptance ok, 420/420 golden, 20 skill files current.Coverage (
scripts/cover.sh, lines)Of the new lines, only the
panic!in the unit test helper is not run. The other missedissue.rslines predate this change.watch.rsvaries between runs on timing-dependent reconnect paths, before and after; its new line is covered.