feat(linear): support custom workflow statuses

[maksymilian-majer]

Summary

Adds database-backed workflow status definitions and wires them through Linear project setup, custom agent dispatch, dashboard stats filters, prompt loading, and CLI management. This lets Linear statuses map to custom Cascade workflow stages and custom agents while preserving the built-in statuses as immutable defaults.

Also routes manual/retry runs through the normal execution lifecycle so successful implementation retries still create/link PRs and advance the work item lifecycle.

Screenshots

Custom statuses

Status mapping to agent

Custom agent triggers

Test Plan

• Unit tests pass (npm test)
• Linter passes (npm run lint)
• Type check passes (npm run typecheck)
• Tested manually: configured Linear custom statuses/agents locally, exercised PRD/story/phased-plan/implementation flow, verified retry/manual implementation lifecycle behavior

Additional verification run locally:

• npm run build
• npm run verify
• pre-push npm run test:fast

Checklist

• My code follows the project's code style
• I have added tests for new functionality
• I have updated documentation if needed
• My commits follow Conventional Commits

[codecov]

Codecov Report

❌ Patch coverage is 98.32402% with 9 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/cli/dashboard/workflow-statuses/list.ts	85.29%	4 Missing and 1 partial ⚠️
src/api/routers/prompts.ts	93.33%	1 Missing ⚠️
src/cli/dashboard/workflow-statuses/create.ts	97.67%	1 Missing ⚠️
...epositories/workflowStatusDefinitionsRepository.ts	98.78%	1 Missing ⚠️
src/triggers/shared/pm-status.ts	95.45%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[nhopeatall]

Summary

Requesting changes: the Linear wizard no longer exposes the existing friction status slot once workflow statuses load, which regresses friction reporting setup.

Code Issues

Should Fix

• web/src/components/projects/pm-providers/linear/wizard.ts:184 — Switching the Linear mapping UI to workflowStatuses.list drops the friction slot because BUILTIN_WORKFLOW_STATUSES does not include it. statuses.friction is still part of the Linear config contract and is required by friction materialization, so new Linear projects can no longer configure friction reports through the wizard.

🕵️ codex · gpt-5.5 · run details

[nhopeatall]

Summary

Requesting changes because custom Linear statuses can dispatch but do not participate in lifecycle moves, and Linear setup can auto-enable backlog-manager unexpectedly.

Code Issues

Should Fix

• src/pm/linear/integration.ts:92 - Custom workflow statuses saved in linearConfig.statuses are not included in the normalized lifecycle config. A custom agent can declare lifecycle.moveOnSuccess: story because the schema accepts arbitrary strings, but PMLifecycleManager.handleSuccess() resolves moves through pmConfig.statuses[moveOnSuccess]; for story that lookup is undefined, so safeMove skips the transition. Any PRD/story/phased-plan style flow that relies on the normal lifecycle will dispatch when a user manually moves into the custom state, but it will not advance to the next custom Linear state on success. Include custom status mappings in resolveLifecycleConfig and widen ProjectPMConfig.statuses accordingly.
• web/src/components/projects/pm-providers/save-trigger-configs.ts:30 - Linear setup now builds trigger configs for every mapped workflow status with an agent type. Since BUILTIN_WORKFLOW_STATUSES gives backlog agentType: 'backlog-manager', a project that maps Backlog during Linear setup gets a DB override enabling backlog-manager for pm:status-changed, even though that trigger's YAML default is false and the Trello/JIRA setup paths still only enable implementation/splitting/planning. After that, moving any Linear issue into Backlog can fire backlog-manager and pull work forward unexpectedly. Filter default-disabled built-ins such as backlog-manager out of the auto-created configs, or make the allowlist explicit.

🕵️ codex · gpt-5.5 · run details

[maksymilian-majer]

Updated the PR after the latest review pass.

Changes pushed in 5dc43e73:

• Linear lifecycle config now preserves all configured status mappings, including custom workflow status keys, so lifecycle moves can target custom statuses like prd, story, or phased-plan.
• The PM wizard trigger setup now auto-enables only the default built-in status triggers that should start runs (splitting, planning, todo). Built-in slots such as backlog remain opt-in, while custom mapped statuses with agent definitions still get trigger configs.
• Added regression coverage for custom Linear mappings, lifecycle prepare/success moves to custom keys, built-in friction/no-agent status metadata, and trigger auto-enable behavior.

Verification:

• npm test -- tests/unit/pm/linear-integration.test.ts tests/unit/pm/linear/integration.test.ts tests/unit/pm/lifecycle.test.ts tests/unit/pm/lifecycle-config-shape.test.ts tests/unit/web/pm-wizard-hooks.test.ts tests/unit/pm/workflow-statusDefinitions.test.ts
• npm run typecheck
• pre-push npm run test:fast -- --changed origin/dev ... passed: 316 files, 6084 tests, 23 skipped.

[nhopeatall]

Summary

Requesting changes: manual/retry runs now always use PM lifecycle defaults, which regresses PR-based agent retries by mutating linked PM work items.

Code Issues

Should Fix

• src/triggers/shared/manual-runner.ts:152 — PR-based manual/retry runs now enter runAgentExecutionPipeline without the GitHub execution config. The normal GitHub path explicitly sets skipPrepareForAgent, skipHandleFailure, and handleSuccessOnlyForAgentType so review/respond-to-ci/respond-to-review runs do not add/remove PM lifecycle labels or post PM failure comments. A retry of a linked review run can now resolve the work item from the PR, call prepareForAgent, then handleSuccess, and mark the PM item processing/processed even though no implementation lifecycle occurred. Preserve the GitHub execution config for PR-based manual/retry runs, or scope this new lifecycle behavior to the PM/implementation retry case.

🕵️ codex · gpt-5.5 · run details

[nhopeatall]

This now runs every manual/retry invocation through the shared pipeline with the default PM lifecycle config. That is correct for the implementation retry case this PR is trying to fix, but it is not equivalent for PR-based agents: the normal GitHub execution path uses skipPrepareForAgent, skipHandleFailure, and handleSuccessOnlyForAgentType: 'implementation' so review/respond-to-ci/respond-to-review do not mutate the linked PM item. With this path, retrying a linked review run can resolve workItemId, add/remove processing labels, and mark the PM item processed on success. Please preserve the GitHub execution config for PR-based manual/retry runs or limit the lifecycle path to the PM/implementation case.

[maksymilian-majer]

Fixed the latest manual/retry lifecycle review issue in 00d95a99.

Changes:

• PR-based manual/retry runs for non-PM agents now preserve the GitHub execution config: skipPrepareForAgent, skipHandleFailure, and handleSuccessOnlyForAgentType: 'implementation'.
• PM-focused PR-based agents keep the default PM lifecycle, so implementation-style retries can still advance the work item correctly.
• Deleting a custom DB-backed agent now clears matching workflow_status_definitions.agent_type references to avoid stale dispatch mappings. No FK and no migration were added, because YAML-only agents remain valid references.
• Added regression coverage for both areas.

Verification:

• npm run typecheck
• npm test -- tests/unit/triggers/manual-runner.test.ts tests/unit/triggers/github-integration.test.ts tests/unit/triggers/agent-execution.test.ts tests/unit/api/routers/agentDefinitions.test.ts tests/unit/db/repositories/workflowStatusDefinitionsRepository.test.ts
• TEST_DATABASE_URL=postgresql://cascade_test:cascade_test@127.0.0.1:5433/cascade_test npx vitest run --project integration tests/integration/db/workflowStatusDefinitionsRepository.test.ts

Note: pre-push npm run test:fast -- --changed origin/dev was run and reached 315/316 passed files, but stopped on an unrelated timeout in tests/unit/agents/definitions/async-resolver.test.ts seed idempotency. Re-running that specific seed test with a larger timeout passes locally; the test spends about 11.7s in the seed path and exceeded its hard 15s timeout under full-suite load.