feat(cli): bgagent linear remove-workspace command

[isadeks]

Summary

Add a bgagent linear remove-workspace <slug> CLI command that lets a Linear-workspace admin deregister a workspace previously onboarded via bgagent linear setup or bgagent linear add-workspace. Surfaced during PR #160 review (krokoko) — tracked as a follow-up that never landed.

Today, removing a workspace requires manual surgery across DDB and Secrets Manager, which is error-prone and undocumented.

Motivation

Workspace onboarding is a one-line CLI command. Workspace removal isn't — operators have to:

1. Find the row in LinearWorkspaceRegistryTable and either delete it or flip status to revoked
2. Delete the per-workspace OAuth secret in Secrets Manager (bgagent-linear-oauth-<slug>)
3. (Optional) Clean up LinearProjectMappingTable rows for that workspace

Without the command, a workspace removal can leave dangling secrets, stale registry rows that the resolver still reads, or orphan project mappings that confuse operators.

Proposed UX

$ bgagent linear remove-workspace acme
Found workspace 'acme' (Linear workspace ID: ws-uuid-1234, status=active)
This will:
  • Mark the registry row as status=revoked (preserves audit trail)
  • Delete the Secrets Manager secret 'bgagent-linear-oauth-acme'
  • Delete 4 project mappings for this workspace

Type the workspace slug to confirm: acme
✔ Registry row revoked
✔ Secret deleted
✔ 4 project mappings removed
Done.

Flags:

• --purge — also delete the registry row entirely (default: keep with status=revoked for audit)
• --keep-mappings — leave LinearProjectMappingTable rows alone
• --yes — skip the slug-confirmation prompt (for scripted use)

Acceptance criteria

• New CLI command bgagent linear remove-workspace <slug> registered under cli/src/commands/linear/
• Calls a new authenticated REST endpoint (DELETE /v1/linear/workspaces/{slug}) — keeps DDB / Secrets Manager grants on the API role, not on every CLI user
• New Lambda handler under cdk/src/handlers/linear/ that:
  • Verifies the caller is the workspace admin (matches the user who ran setup for that slug — same auth pattern as existing OAuth admin commands)
  • Updates LinearWorkspaceRegistryTable row to status='revoked' (or deletes it with --purge)
  • Deletes the corresponding bgagent-linear-oauth-<slug> secret from Secrets Manager
  • Optionally deletes LinearProjectMappingTable rows where workspace_slug = <slug>
• Resolver code (linear-oauth-resolver.ts + Python equivalent) treats status='revoked' as fail-closed (already does — re-verify under test)
• Tests: jest for the handler (happy path, not-found, not-admin, secret-already-gone, mappings-empty); CLI command jest test (flags, prompts, error surfaces)
• Doc: short section in docs/guides/LINEAR_SETUP_GUIDE.md under "Removing a workspace"

Out of scope

• Re-onboarding a previously-revoked workspace (separate issue if needed; today operators can just bgagent linear add-workspace again)
• UI in any web console — CLI only

References

• Original surface in PR feat(linear): OAuth migration with per-workspace token storage (Phase 2.0b) #160 review (krokoko, "or task only")
• Phase 2.0b shipped via PR feat(linear): OAuth migration with per-workspace token storage (Phase 2.0b) #160 (merged 2026-05-26)
• Related: registry table schema in cdk/src/constructs/linear-integration.ts, OAuth secret naming convention in cdk/src/handlers/shared/linear-oauth-resolver.ts

Estimate

~1–2 hours: handler + CLI command + tests + doc snippet. No infra changes (existing tables and secret prefix are reused).

[scottschreckengaust]

@scottschreckengaust (agent:w7) working on it — #306 — branch feat/issue-306-linear-remove-workspace

[scottschreckengaust]

🤖 @scottschreckengaust (agent:w7) — signing out, over and out.

DRAFT: PR #681 opened (draft); body has Closes #306. Ships the bgagent linear remove-workspace <slug> command + DELETE /v1/linear/workspaces/{slug} handler/route + admin-only, fail-closed teardown (revoke registry row, delete OAuth secret, optional mapping cleanup; --purge/--keep-mappings/--yes). In the orchestrator's review pipeline.

[scottschreckengaust]

The LinearProjectMappingTable cleanup criterion is deferred to #687 (record linear_workspace_id at onboard time). PR #681 (Closes #306) ships the working command but removed the mapping-cleanup path because no row carries a workspace id today (it matched nothing). #687 restores it correctly. 🤖 @scottschreckengaust (orchestrator)