Summary

Extend Vigilante's mixed-backend issue tracking so vigilante watch can be configured against Linear in a way that is operationally safe. When a repository is watched with --issue-tracker linear, Vigilante should verify that the Linear CLI dependency is installed and authenticated up front, persist the Linear-specific watch configuration, and use Linear stages plus issue labels when selecting work.

Problem

• Vigilante already models linear as an issue backend in state and backend-neutral interfaces, but the watch flow and queue-selection semantics are still GitHub-oriented.
• A user can conceptually choose Linear as the issue tracker, but there is no watch-time validation that the required Linear dependency is available locally or that the local session is authenticated.
• The current watch surface only exposes GitHub-style label filtering. There is no way to express that Linear-backed work should only be dispatched from a specific workflow stage such as Todo.
• Without explicit preflight checks and stage-aware filtering, Linear-backed watch targets will either fail late or dispatch the wrong work items.

Context

• Repository: aliengiraffe/vigilante
• The current watch command only supports --label, --assignee, --max-parallel, --provider, --branch, and --track-default-branch.
• internal/state.WatchTarget already persists IssueBackend, GitBackend, PRBackend, and ProjectRef, and tests already cover mixed-backend modeling such as Linear issues plus GitHub pull requests.
• The backend abstractions already separate IssueTracker and LabelManager, so this work should extend that direction rather than re-introducing GitHub-specific assumptions into the orchestration loop.
• The intended Linear dependency is the linear-cli tool. For this issue, Vigilante should treat that CLI as a required local dependency when --issue-tracker linear is selected.

Desired Outcome

• Users can register a repository with Linear as the issue tracker by using vigilante watch --issue-tracker linear.
• During that watch command, Vigilante verifies that the required Linear CLI is installed and that the current machine is authenticated for Linear before the watch target is saved.
• Users can optionally specify a stage gate such as --issue-tracker-stage todo, and Vigilante only treats Linear issues in that stage as eligible for dispatch.
• Label-based filtering continues to work for watched targets, but when the issue tracker is Linear the labels are resolved against Linear issue labels instead of GitHub issue labels.
• Mixed-backend behavior remains intact: Linear can provide issue tracking while Git hosting and PR management stay on GitHub.
• Out of scope: implementing non-Linear backends beyond the abstractions needed here, changing PR hosting away from GitHub, or redesigning unrelated watch/daemon UX.

Implementation Notes

• Extend the watch CLI surface and persisted watch-target state to capture the issue tracker choice and an optional issue-tracker stage filter.
• Add watch-time preflight for --issue-tracker linear that fails fast with actionable messaging when the Linear CLI is missing or not authenticated.
• Keep the dependency check backend-specific. GitHub-backed watch targets should not pay a Linear preflight cost.
• Define how Linear projects are identified for watched targets. Reuse existing backend-neutral fields where appropriate instead of introducing duplicate configuration.
• Ensure the dispatch path, issue selection logic, and any label-management flow use backend-neutral interfaces so Linear labels/stages can participate without special-casing the rest of the session lifecycle.
• The stage filter should be optional but explicit. If omitted for a Linear target, use a documented default that matches the product decision for the initial implementation. The user expectation called out here is Todo, or an equivalent explicit stage provided via --issue-tracker-stage.
• Failures from Linear CLI discovery or auth checks should happen before the watch target is persisted, and tests should verify that partially configured Linear watch targets are not saved.

Acceptance Criteria

• vigilante watch accepts an issue-tracker selection that can be set to linear without regressing the existing GitHub default behavior.
• When vigilante watch --issue-tracker linear <path> is run and the required Linear CLI is not installed, the command exits with a clear error and does not persist the watch target.
• When vigilante watch --issue-tracker linear <path> is run and the Linear CLI is installed but not authenticated, the command exits with a clear error and does not persist the watch target.
• A Linear-backed watch target can persist an optional stage filter from a flag such as --issue-tracker-stage todo.
• When a Linear stage filter is configured, Vigilante only dispatches Linear issues whose current workflow stage matches the configured stage.
• If no explicit Linear stage filter is provided, Vigilante uses the documented default stage behavior for Linear-backed watch targets and covers that behavior with tests.
• Existing label-based filtering continues to work for GitHub issue tracking exactly as it does today.
• For Linear-backed issue tracking, label filtering and any managed-label synchronization operate against Linear issue labels without breaking GitHub-backed label management.
• Existing mixed-backend support remains valid, including Linear issues with GitHub git/PR workflows.

Testing Expectations

• Add or update CLI/watch command tests covering new flags, validation failures, persisted watch-target state, and successful Linear watch registration.
• Add backend/unit tests for Linear-specific preflight behavior, stage matching, and label matching.
• Add or update orchestration/selection tests so a Linear-backed target only dispatches work items from the configured stage and does not regress GitHub label selection.
• Cover negative paths where the Linear CLI binary is missing, auth is absent/expired, or stage names do not resolve cleanly.
• Verify state serialization for any new watch-target fields and backward compatibility when older watchlist entries omit them.

Operational / UX Considerations

• Error messages should tell the operator what to install or re-authenticate, not just that the command failed.
• Document the new watch flags and the required Linear CLI dependency in the README/help text.
• Be explicit about how stage names are normalized or compared so operators do not have to guess whether Todo, todo, or another workflow name is required.
• If Linear label management does not support exactly the same semantics as GitHub labels, document the supported behavior and preserve GitHub behavior unchanged.