feat: projects update + initiatives (RUSH-2284)

[muqsitnawaz]

What

Feature (RUSH-2284) — closes the Linear CLI milestone Project-update + Initiative support.

Closes the GraphQL gap: the CLI can set a project description and create/link initiatives.

Changes

Surface	Behavior
linear projects update <name|id>	--description / --description-file, --name, --lead (none clears), --start/--target (none clears), --state (type or status name → statusId)
linear initiatives	list / show / create / update / link / unlink / archive
projects show	prints Description when set
Docs	README, skill.md, CHANGELOG 0.17.0
Tests	status resolve, initiative resolve, link find, argv shim (update not swallowed as show)

Strict resolution: unknown project/initiative names exit non-zero with suggestions.

Run result (live)

$ python3 -m unittest test_linear -q
Ran 84 tests in 0.015s
OK

$ ./linear --version
linear-cli 0.17.0

$ ./linear projects update "Linear CLI" --description "CLI project for agent workflows. (verified RUSH-2284 ...)"
Updated project 'Linear CLI'  (4c1d7cf8-421f-4705-b230-293bb2fbe4a8)
  Description: CLI project for agent workflows. (verified RUSH-2284 projectUpdate 2026-08-06T08:29Z)
# (description restored after round-trip)

$ ./linear initiatives
1 initiative(s):
  Rush = the default Agent OS               Active        target: 2026-12-31    owner: -

$ ./linear initiatives create --name "RUSH-2284 overnight probe" --status Proposed --target 2026-08-07
Created initiative 'RUSH-2284 overnight probe'  status: Proposed  (dec50829-...)

$ ./linear initiatives link "RUSH-2284 overnight probe" --project Prex
Linked initiative 'RUSH-2284 overnight probe' <-> project 'Prex'  (e7dc45f1-...)

$ ./linear initiatives unlink ... ; archive ...
Unlinked ... / Archived ...

$ ./linear projects update "Definitely No Such Project XYZ" --description x
Error: project 'Definitely No Such Project XYZ' not found.   # exit 1

Ticket: https://linear.app/getrush/issue/RUSH-2284/linear-cli-project-description-update-initiative-support

Out of scope

• Release/tag/fleet upgrade (follow after merge)
• Issue↔initiative linking (API is project-scoped join rows)

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[prix-cloud]

Code Reviewer

Verdict: Ready to merge

Build: 0.17.0 — version string, help menus, argv shim all verified
Tests: 84/84 pass (0.011s)

Changes that work well

• Clean function decomposition. _project_update, _initiative_create, _initiative_show, etc. follow the same pattern as the existing _project_create, _project_show, _cycle_update — easy to navigate and consistent with the codebase's conventions.

• Strict resolution with suggestions. Unknown project/initiative names raise LookupError with close-match suggestions and exit non-zero. This is consistent with the existing project resolution pattern (resolve_project_id(strict=True)) and prevents silent no-ops.

• --none clearing is consistent. The none keyword for clearing --lead, --start, --target, and --owner is handled uniformly across both projects update and initiatives update.

• Status resolution is well-thought-out. resolve_project_status_id checks type first (so --state started works), then exact name, then substring — with a single-match guard on substring to avoid ambiguity.

• Idempotent link. _initiative_link checks for an existing join row before creating, so re-linking is safe rather than erroring.

• Fully paginated where it matters. Both list_initiatives and find_initiative_to_project_id paginate through the connection, so workspaces with many initiatives/link rows don't silently miss data.

• Tests cover the key edge cases. The ProjectStatusResolveTest, InitiativeResolveTest, InitiativeToProjectFindTest, and ProjectsArgvShimTest classes exercise status resolution by type/name/substring, initiative UUID passthrough, strict-unknown raises, exact-name-beats-substring, link-row matching, and the argv-shim regression that projects update is not swallowed as projects show update.

Issues that need attention

None. The diff is clean, well-tested, and follows the existing codebase patterns. No stubs, no placeholders, no env-var-based config, no cross-file consistency issues.

Things to verify manually

• The initiatives show --json flag uses the same argparse.SUPPRESS default as the existing projects show --json and milestones list --json — intentional to avoid overwriting the parent --json when the argv shim injects show. This is correct but worth smoke-testing with --json placed before and after the show subcommand.

---

Reviewed by Code Reviewer — actually ran the build and tests on this branch.

[muqsitnawaz]

Verification: CI green (unittest SUCCESS). 84 unit tests OK. Live: projects update description round-trip on Linear CLI; initiatives create/link/unlink/archive on throwaway; fail-loud on unknown names. Schema mutations match. prix-cloud paused (#1767).

[muqsitnawaz]

Non-author review APPROVE: projectUpdate + initiatives GraphQL match schema; strict resolve; tests green; no stubs.

Independent review evidence (this session)

GraphQL ↔ live Linear schema (introspected against api.linear.app)

Mutation / field	Schema
projectUpdate(id: String!, input: ProjectUpdateInput!)	present; input has statusId, name, description, leadId, startDate, targetDate
initiativeCreate / initiativeUpdate	present; status: InitiativeStatus
InitiativeStatus	Proposed | Planned | Active | Completed | Canceled (exact match to CLI allowlist)
ProjectStatusType	backlog | planned | started | paused | completed | canceled
initiativeToProjectCreate / Delete	present; create input requires initiativeId + projectId
initiativeArchive	present
initiative.projects	ProjectConnection (show query OK live)
projectStatuses / initiatives / initiativeToProjects	all on Query root

Strict resolve (file:line)

• linear:2787 — _project_update uses resolve_project_id(..., strict=True) → LookupError → exit 1
• linear:2825-2830 — --state via resolve_project_status_id raises on unknown
• linear:3110, 3211, 3278, 3317, 3344 — initiative write paths use resolve_initiative_id(..., strict=True)
• linear:3279, 3318 — link/unlink also strict-resolve the project

Tests

$ python3 -m unittest test_linear -v
Ran 84 tests in 0.004s
OK

CI: unittest SUCCESS (×2 check runs). New coverage: ProjectStatusResolveTest, InitiativeResolveTest, InitiativeToProjectFindTest, ProjectsArgvShimTest.

No production stubs

Production path uses real gql(...) mutations. Test doubles (fake_gql / fake_list) are unit-test only.

Note on approve button

gh pr review --approve is blocked for the PR author (muqsitnawaz). Technical verdict is still APPROVE. Automated non-author clear already on thread: prix-cloud → Ready to merge.

No REQUEST_CHANGES findings.