plan_my_stuff 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69661ace546ff5f775e0e9fb5e4a153c3aca9e68da0b568e85238d8b66ef620a
-  data.tar.gz: e0698c727fe6c3f1e8e135d0a2b1860731188dc01496065e3622a0a1d6ef0c45
+  metadata.gz: 6799008cb353423175bdd3132e0fa5f14981b3710378c3b0886a8e9a2394b610
+  data.tar.gz: 75b8336ec9aabd1d77a2642de77c9e46310dda3da49e6abd97b997927e906d05
 SHA512:
-  metadata.gz: 876ac7c9c1baf371e09d81535324ae9a35bcd1c3a30509931395e274a229fcf25397ba1377450cb6a8ad6465f0474174ea664579b59f0d407c9b83ee08523647
-  data.tar.gz: 89c4a1865f38c614c05d802c02d267b0ff2e83339da936403fac08f3d98476a6b87b722eecf422b5ee8f101f5db1ce75e8d3f836a3f54dd0ca86713df3146feb
+  metadata.gz: fdb5b8790905ff4f529496ad2a5c63b13a59a58ce524a8df79b20b0efc536854bc986f0e2fe7896b77bfe9b0a15598b6212a83991d46c9925e4dbf9eecab4871
+  data.tar.gz: b5c150efa84a7ed3143935216d0ac52ae9c8fa7d99cb45b6add6552c13f3b66fad2f604e1aa8871cb05fc69b3aa16e650bce14a60ad1490d0650af3a3e646d91

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.8.0
+
+### Breaking
+
+- Issue show "Take" button is now hidden when the issue already has assignees, and `Issues::TakesController#create` rejects the request with a flash error naming the existing assignee. Best-effort race guard for two users clicking Take simultaneously — without it, GitHub silently piles the second user on as a co-assignee.
+  - Guard lives in the controller, not `Pipeline.take!` itself, because webhook paths (`handle_issue_assigned`, `handle_projects_v2_item`, `handle_draft_opened`, `handle_converted_to_draft`) legitimately call `take!` on already-assigned issues
+- `Issue#add_viewers` / `Issue#remove_viewers` renamed to `Issue#add_viewers!` / `Issue#remove_viewers!` for consistency with other mutating instance methods (`approve!`, `close!`, etc.)
+- `Approval#status` extended to a 3-state model (`pending`, `approved`, `rejected`); `Approval` gains a `rejected_at` attribute serialized in `to_h` and the metadata blob. Existing approvals deserialize unchanged (`rejected_at` defaults to `nil`)
+- `Issue#fully_approved?` now requires every approver to be `approved` — a single rejection blocks the gate until revoked. Previously equivalent to `pending_approvals.empty?`, which silently treated rejections as "done"
+- `Issue#revoke_approval!` accepts either an `approved` or `rejected` source state (previously only `approved`); raises `ValidationError` when the target is still `pending`. Authorization error message updated to "another user's response"
+
+### Added
+
+- `CONFIGURATION.md` documents every `PlanMyStuff::Configuration` option grouped by concern; `README.md` Configuration section trimmed to the two required options plus a link
+- Install generator's initializer template now includes the four pipeline options previously missing from it: `pipeline_testing_field_name`, `pipeline_testing_values`, `pipeline_completion_purge_enabled`, `pipeline_completion_ttl_hours`
+- Project show "Remove from project" button (and `DELETE /projects/:project_id/items/:id` route on `ProjectItemsController`) lets the user remove an item from a project board without bouncing out to GitHub. Calls `ProjectItem#destroy!` which fires `plan_my_stuff.project_item.removed`
+- Issue show "Release" button (and `DELETE /issues/:issue_id/take` route on `Issues::TakesController`) lets a dev who took an issue undo their assignment from the same view, without bouncing out to GitHub or the project board. When the current user is the sole assignee the issue's GitHub assignees are cleared and the project item is removed from the pipeline (`project_item.destroy!`); when other assignees remain the current user is unassigned via `project_item.assign!(remaining)` and the item stays on the project
+- `config.import_access_token` classic PAT (requires `repo` scope) used exclusively for the Issues Import API (`golden-comet-preview`); fine-grained tokens are not supported by that endpoint. Optional — defaults to `nil`
+- `Issue.import!(payloads)` POSTs an `Array<Hash>` (one POST per payload) to GitHub's "Import Issues" preview endpoint and returns one status hash per input. Each payload must include `:repo` plus the GitHub-shaped `:issue` / `:comments` keys; payloads are passed through unchanged otherwise
+- `Issue.check_import!(import_id, repo:)` polls a previously-submitted import for its status
+- `Issue#created_at` / `Comment#created_at` attributes hydrated from GitHub's `created_at` field
+- `Issue#issue_type` reader hydrated from GitHub's native `type.name`. `Issue.create!` and `Issue.update!` accept an `issue_type:` kwarg as a String (passed through), Symbol shortcut (`:bug`, `:feature`, `:it_issue`, `:other`, `:performance`, `:question`, `:task`), or `nil`. On `update!`, omitting the kwarg leaves the type untouched; passing `nil` clears it
+- `config.issue_types` Hash{String => String} maps canonical type names to org-specific display names so consuming apps can rename without touching call sites (e.g. `{ 'Feature' => 'Enhancement' }`); missing keys pass through unchanged
+- `config.controller_rescue` Proc invoked from every user-facing controller `rescue` block (after the gem logs the error and stack trace) so consuming apps can forward swallowed errors to their monitoring service
+- `Issue#reject!(user:)` symmetric with `approve!`; accepts either `pending` or `approved` source state and raises `ValidationError` when already rejected. Fires `plan_my_stuff.issue.approval_rejected` and, when the flip drops the issue out of `fully_approved?`, `approvals_invalidated(trigger: :rejected)`
+- `Issue#approve!` now accepts either `pending` or `rejected` source state; raises `ValidationError` only on `approved -> approved`. Clears `rejected_at` on the rejected -> approved transition
+- `Issue#rejected_approvals` reader returns the subset of approvers with `status == 'rejected'`
+- New events: `plan_my_stuff.issue.approval_rejected` and `plan_my_stuff.issue.rejection_revoked` (the latter fires when revoking a rejection back to pending)
+- Approvals partial renders a `Reject` button alongside `Approve` for pending approvers, a `rejected at <ts>` row, a parenthetical rejected count in the header, and a `Revoke` button for either non-pending state
+
+## 0.7.0
+
+### Added
+
+- `Issue#user_link` returns the per-issue URL in the consuming app, computed from `config.issues_url_prefix` + issue number
+
+### Changed
+
+- GitHub issues created/updated by PMS now render a markdown link `[Org/Repo#number](user_link)` as the visible body (previously empty); skipped when `issues_url_prefix` is unset
+
 ## 0.6.0
 
 ### Breaking
@@ -7,7 +47,7 @@
 - `Pipeline.submit!` removed; consuming apps that called it directly should switch to `ProjectItem.create!` + `Pipeline.take!`
 - `Pipeline::Status::SUBMITTED` and `Pipeline::Status::TESTING` constants removed; `Status::ALL` no longer includes them
 - `Pipeline.request_testing!` no longer moves the `Status` field — it now writes to a separate `Testing` single-select custom field on the pipeline project. The pipeline project must have a `Testing` field with `Testing` / `Not testing` options
-- Active pipeline status set is now `Started → In Review → Ready for Release → Release in Progress → Completed`
+- Active pipeline status set is now `Started -> In Review -> Ready for Release -> Release in Progress -> Completed`
 
 ### Added
 

data/README.md

@@ -43,7 +43,7 @@ The gem supports three markdown rendering options. The chosen gem must be in you
 | None (raw) | Nothing | `config.markdown_renderer = nil` |
 
 > [!NOTE]
-> If you pick `:commonmarker`, use v1.0+ — the v0.23 → v1.0 rewrite renamed the module to `Commonmarker`, swapped `render_html` for `to_html`, and moved options from a symbol array to a nested hash. Apps still on commonmarker < 1.0 must upgrade or switch to `:redcarpet` / `nil`.
+> If you pick `:commonmarker`, use v1.0+ — the v0.23 -> v1.0 rewrite renamed the module to `Commonmarker`, swapped `render_html` for `to_html`, and moved options from a symbol array to a nested hash. Apps still on commonmarker < 1.0 must upgrade or switch to `:redcarpet` / `nil`.
 
 ### Overriding views
 
@@ -55,58 +55,21 @@ rails generate plan_my_stuff:views
 
 ## Configuration
 
+The install generator drops a fully-commented initializer at
+`config/initializers/plan_my_stuff.rb`. Two options are required:
+
 ```ruby
-# config/initializers/plan_my_stuff.rb
-PlanMyStuff.configure do |config|
-  # Auth (PAT from a bot account with repo + project scopes)
+PMS.configure do |config|
   config.access_token = Rails.application.credentials.dig(:plan_my_stuff, :github_token)
-
-  # Organization
   config.organization = 'YourOrganization'
-
-  # Named repo configs
-  config.repos[:marketing_website] = 'YourOrganization/MarketingWebsite'
-  config.repos[:cms_website] = 'YourOrganization/CMSWebsite'
-  config.default_repo = :cms_website
-
-  # Default project board
-  config.default_project_number = 123
-
-  # User class (your app's model)
-  config.user_class = 'User'
-  config.display_name_method = :full_name
-  config.user_id_method = :id
-
-  # Support role check (symbol or proc)
-  config.support_method = :support?
-
-  # Markdown rendering (:commonmarker, :redcarpet, or nil)
-  config.markdown_renderer = :commonmarker
-
-  # Request gateway (proc or nil; nil = always send)
-  config.should_send_request = nil
-
-  # Background jobs (when gateway defers a request)
-  config.job_classes = {
-    create_ticket: 'PmsCreateTicketJob',
-    post_comment:  'PmsPostCommentJob',
-    update_status: 'PmsUpdateStatusJob'
-  }
-
-  # Fallback actor for notification events when a caller does not pass user:
-  config.current_user = -> { Current.user }
-
-  # Custom fields (stored in issue/comment metadata)
-  config.custom_fields = {
-    ticket_type: { type: :string },
-    notification_recipients: { type: :array }
-  }
-
-  # App name (appears in metadata)
-  config.app_name = 'MyApp'
 end
 ```
 
+Everything else is optional. See [CONFIGURATION.md](CONFIGURATION.md) for the
+full option reference grouped by concern (repos, projects, user
+integration, markdown, request gateway, custom fields, pipeline,
+reminders, archiving, AWS webhook, caching, routes, controllers).
+
 The `PMS` alias is available for brevity: `PMS.configure`, `PMS::Issue.find`, etc.
 
 ## Architecture
@@ -115,7 +78,7 @@ All state lives on GitHub. The gem exposes it through ActiveRecord-style domain
 
 ### Domain class hierarchy
 
-```
+```text
 ApplicationRecord                 # includes ActiveModel::Model, Attributes, Serializers::JSON
 ├── Issue                         # GitHub Issue
 ├── Comment                       # GitHub Issue comment
@@ -160,10 +123,10 @@ issue = PMS::Issue.create!(
 )
 
 # Find
-issue = PMS::Issue.find(repo: :cms_website, number: 123)
+issue = PMS::Issue.find(123, repo: :cms_website)
 issue.title
 issue.body              # body without metadata
-issue.metadata          # PlanMyStuff::IssueMetadata
+issue.metadata          # PMS::IssueMetadata
 issue.visible_to?(user) # visibility check
 issue.comments          # all comments
 issue.pms_comments      # only PMS-created comments
@@ -179,28 +142,63 @@ issue.update!(state: :closed)
 issue.update!(state: :open)
 
 # Viewer management (visibility allowlist)
-issue.add_viewers(user_ids: [5, 12], user: current_user)
-issue.remove_viewers(user_ids: [5], user: current_user)
+issue.add_viewers!(user_ids: [5, 12], user: current_user)
+issue.remove_viewers!(user_ids: [5], user: current_user)
 ```
 
+#### Importing existing issues
+
+`PMS::Issue.import!` wraps GitHub's "Import Issues" preview endpoint. It takes an array of GitHub-shaped payloads (one POST per payload) and returns one status hash per input. Payloads are passed through unchanged except for `:repo`, which is extracted to build the request URL.
+
+> [!CAUTION]
+> If you choose to use `PMS::Issue.import!`/`PMS::Issue.check_import!`, you must configure `import_access_token`
+
+```ruby
+payloads = [
+  {
+    repo: :cms_website,
+    issue: {
+      title:      '[Rawr-12517] Delete contractor check payment',
+      body:       "Imported from YouTrack...",
+      labels:     ['imported-from-youtrack', 'priority:normal'],
+      created_at: '2026-04-28T16:04:59Z',
+    },
+    comments: [
+      { body: 'first comment',  created_at: '2026-04-28T16:26:08Z' },
+      { body: 'second comment', created_at: '2026-04-28T16:26:29Z' },
+    ],
+  },
+]
+
+statuses = PMS::Issue.import!(payloads)
+status   = PMS::Issue.check_import!(statuses.first[:id], repo: :cms_website)
+# => { id: ..., status: 'imported', issue_url: '.../issues/123' }
+```
+
+Notes:
+
+- Each payload MUST include `:repo` (symbol, string, or `PMS::Repo`); a missing `:repo` raises `ArgumentError`.
+- The gem does not embed PMS metadata into the payload — callers are responsible for any metadata or formatting they want to preserve from the source system.
+- The endpoint is async: `import` returns `{ id:, status: 'pending', url: ... }`; poll `check_import` until `status` is `'imported'` or `'failed'`.
+- Requires a classic GitHub PAT with the `repo` scope; fine-grained tokens are rejected with 403.
+
 ### Comments
 
 ```ruby
 # Create
 comment = PMS::Comment.create!(
-  repo: :cms_website,
-  issue_number: 123,
+  issue: issue,
   body: 'Deployed fix to staging, please retest.',
   user: current_user,
   visibility: :public   # or :internal (support-only)
 )
 
 # List
-comments = PMS::Comment.list(repo: :cms_website, issue_number: 123)
-comments = PMS::Comment.list(repo: :cms_website, issue_number: 123, pms_only: true)
+comments = PMS::Comment.list(issue: issue)
+comments = PMS::Comment.list(issue: issue, pms_only: true)
 
 comment.body            # visible text
-comment.metadata        # PlanMyStuff::CommentMetadata (nil for non-PMS comments)
+comment.metadata        # PMS::CommentMetadata (nil for non-PMS comments)
 comment.visibility      # :public, :internal, or nil
 comment.pms_comment?    # true/false
 comment.visible_to?(user)
@@ -209,8 +207,8 @@ comment.visible_to?(user)
 ### Labels
 
 ```ruby
-PMS::Label.add(repo: :cms_website, issue_number: 123, labels: ['in-progress'])
-PMS::Label.remove(repo: :cms_website, issue_number: 123, labels: ['triage'])
+PMS::Label.add!(issue: issue, labels: ['in-progress'])
+PMS::Label.remove!(issue: issue, labels: ['triage'])
 ```
 
 ### Projects
@@ -233,10 +231,10 @@ item.move_to!('In Review')
 item.assign!('octocat')
 
 # Add existing issue to project
-PMS::Project.add_item(project_number: 14, issue_repo: :cms_website, issue_number: 123)
+PMS::ProjectItem.create!(issue, project_number: 14)
 
 # Add draft item
-PMS::Project.add_draft_item(project_number: 14, title: 'Draft task', body: 'Details...')
+PMS::ProjectItem.create!('Draft task', draft: true, body: 'Details...', project_number: 14)
 ```
 
 ### Testing tracking
@@ -258,11 +256,11 @@ Per-item sign-off:
 
 ```ruby
 item = project.items.first
-item.update_pass_mode!('all')              # or 'any'
-item.update_testers!(user_ids: [alice.id, bob.id])
-item.update_watchers!(user_ids: [carol.id])
-item.mark_passed!(user: alice)             # flips to Passed when Pass Mode is satisfied
-item.mark_failed!(user: alice, result_notes: 'Reproduced on Safari 17')
+item.update_pass_mode!('all')                            # or 'any'
+item.update_testers!([alice.id, bob.id])
+item.update_watchers!([carol.id])
+item.mark_passed!(alice)                                 # flips to Passed when Pass Mode is satisfied
+item.mark_failed!(alice, result_notes: 'Reproduced on Safari 17')
 ```
 
 A board and its items are editable through the mounted UI at `/testing_projects`.
@@ -279,8 +277,8 @@ Every PMS lifecycle write fires an `ActiveSupport::Notifications` event under th
 | `plan_my_stuff.issue.updated` | `issue.save!` / `issue.update!` (any non-state change) |
 | `plan_my_stuff.issue.closed` | `issue.update!(state: :closed)` |
 | `plan_my_stuff.issue.reopened` | `issue.update!(state: :open)` |
-| `plan_my_stuff.issue.viewers_added` | `issue.add_viewers` |
-| `plan_my_stuff.issue.viewers_removed` | `issue.remove_viewers` |
+| `plan_my_stuff.issue.viewers_added` | `issue.add_viewers!` |
+| `plan_my_stuff.issue.viewers_removed` | `issue.remove_viewers!` |
 | `plan_my_stuff.issue.approval_requested` | `issue.request_approvals!` |
 | `plan_my_stuff.issue.approval_granted` | `issue.approve!` |
 | `plan_my_stuff.issue.approval_revoked` | `issue.revoke_approval!` |
@@ -288,9 +286,9 @@ Every PMS lifecycle write fires an `ActiveSupport::Notifications` event under th
 | `plan_my_stuff.issue.approvals_invalidated` | aggregate — fires when a revoke (or new approver) drops the set out of fully-approved |
 | `plan_my_stuff.comment.created` | `Comment.create!` |
 | `plan_my_stuff.comment.updated` | `comment.save!` / `comment.update!` |
-| `plan_my_stuff.label.added` | `Label.add` |
-| `plan_my_stuff.label.removed` | `Label.remove` |
-| `plan_my_stuff.project_item.added` | `ProjectItem.create!` / `.add_draft_item` |
+| `plan_my_stuff.label.added` | `Label.add!` |
+| `plan_my_stuff.label.removed` | `Label.remove!` |
+| `plan_my_stuff.project_item.added` | `ProjectItem.create!` (issue or `draft: true`) |
 | `plan_my_stuff.project_item.removed` | `project_item.destroy!` |
 | `plan_my_stuff.project_item.assigned` | `project_item.assign!` |
 | `plan_my_stuff.project_item.status_changed` | `project_item.move_to!` |
@@ -306,14 +304,14 @@ All events include:
 
 Additional keys by event:
 
-- `issue.updated` / `comment.updated` → `:changes` — hash of `{ attr => [old, new] }`
-- `issue.viewers_added` / `viewers_removed` → `:user_ids`
-- `issue.approval_requested` → `:approvals` (array of newly-added `PMS::Approval`)
-- `issue.approval_granted` / `approval_revoked` → `:approval` (the flipped `PMS::Approval`)
-- `issue.approvals_invalidated` → `:trigger` — `:revoked` or `:approver_added`
-- `label.added` / `label.removed` → `:labels`
-- `project_item.assigned` → `:assignees`
-- `project_item.status_changed` → `:status`, `:previous_status`
+- `issue.updated` / `comment.updated` -> `:changes` — hash of `{ attr => [old, new] }`
+- `issue.viewers_added` / `viewers_removed` -> `:user_ids`
+- `issue.approval_requested` -> `:approvals` (array of newly-added `PMS::Approval`)
+- `issue.approval_granted` / `approval_revoked` -> `:approval` (the flipped `PMS::Approval`)
+- `issue.approvals_invalidated` -> `:trigger` — `:revoked` or `:approver_added`
+- `label.added` / `label.removed` -> `:labels`
+- `project_item.assigned` -> `:assignees`
+- `project_item.status_changed` -> `:status`, `:previous_status`
 
 ### Actor resolution
 
@@ -345,7 +343,7 @@ expect {
 }.to(have_fired_event('plan_my_stuff.issue.created').with(user: alice))
 
 # Raw capture
-events = PlanMyStuff::TestHelpers::Notifications.capture do
+events = PMS::TestHelpers::Notifications.capture do
   PMS::Issue.create!(...)
 end
 events.first[:name]    # => "plan_my_stuff.issue.created"
@@ -380,15 +378,14 @@ issue.remove_approvers!(user_ids: [alice.id], user: current_user)
 ```ruby
 issue.approvers            # Array<PMS::Approval> — all records (pending + approved)
 issue.pending_approvals    # subset still pending
-issue.approvals_required?  # true iff approvers.any?
+issue.approvals_required?  # true iff approvers.present?
 issue.fully_approved?      # true iff approvals_required? && pending_approvals.empty?
 ```
 
 ### Pipeline gating
 
-`PMS::Pipeline::PendingApprovalsError` is raised when any pending approval exists on the linked issue. Gated transitions:
+`PMS::PendingApprovalsError` is raised when any pending approval exists on the linked issue. Gated transitions:
 
-- `Pipeline.submit!`
 - `Pipeline.take!`
 - `Pipeline.mark_in_review!`
 - `Pipeline.request_testing!`
@@ -406,8 +403,8 @@ See the notifications catalog above — `approval_requested`, `approval_granted`
 require 'plan_my_stuff/test_helpers'
 
 # Build an issue with some approvals already in place (no API call)
-issue = PlanMyStuff::TestHelpers.build_issue
-PlanMyStuff::TestHelpers.stub_approvals(issue, approved: [alice], pending: [bob])
+issue = PMS::TestHelpers.build_issue
+PMS::TestHelpers.stub_approvals(issue, approved: [alice], pending: [bob])
 
 issue.fully_approved?      # false
 issue.pending_approvals    # [PMS::Approval(user_id: bob.id, status: 'pending')]
@@ -493,7 +490,7 @@ An end-user reply on a `closed_by_inactivity` issue auto-reopens it, strips the
 
 ### Scheduling the sweep
 
-The gem ships `PlanMyStuff::RemindersSweepJob`, an ActiveJob that walks a repo's waiting issues and dispatches reminders + auto-closes. Each job self-requeues after perform (default cadence: 6:30am ET next day), so you only need to kick off the initial enqueue — a rake task handles that:
+The gem ships `PMS::RemindersSweepJob`, an ActiveJob that walks a repo's waiting issues and dispatches reminders + auto-closes. Each job self-requeues after perform (default cadence: 6:30am ET next day), so you only need to kick off the initial enqueue — a rake task handles that:
 
 ```bash
 # Enqueue one job per configured repo:
@@ -506,7 +503,7 @@ rake plan_my_stuff:reminders:sweep REPO=element
 You can also schedule from Ruby if you prefer:
 
 ```ruby
-PlanMyStuff::RemindersSweepJob.requeue(:your_repo_key)  # schedules for next_run
+PMS::RemindersSweepJob.requeue(:your_repo_key)  # schedules for next_run
 ```
 
 `retry_on StandardError, attempts: 1` prevents geometric duplicate pile-up on Delayed-style adapters — if perform raises, the follow-up run (already enqueued by the `around_perform` ensure) picks up tomorrow.
@@ -514,7 +511,7 @@ PlanMyStuff::RemindersSweepJob.requeue(:your_repo_key)  # schedules for next_run
 Override the cadence by subclassing:
 
 ```ruby
-class MyRemindersJob < PlanMyStuff::RemindersSweepJob
+class MyRemindersJob < PMS::RemindersSweepJob
   def self.next_run
     4.hours.from_now.utc  # run every 4 hours
   end
@@ -539,7 +536,7 @@ Closed PMS issues that have aged past `config.archive_closed_after_days` (defaul
 4. Stamp `metadata.archived_at`.
 5. Emit `plan_my_stuff.issue.archived` with `reason: :aged_closed`.
 
-The sweep runs inside `PlanMyStuff::RemindersSweepJob` alongside the follow-up reminders sweep — same cadence, same rake task.
+The sweep runs inside `PMS::RemindersSweepJob` alongside the follow-up reminders sweep — same cadence, same rake task.
 
 ### Exclusions
 
@@ -660,7 +657,7 @@ issue.save!                                       # validates; raises ActiveMode
 
 ### Statuses
 
-`PMS::Pipeline::Status::ALL` (in order): `Submitted` → `Started` → `In Review` → `Testing` → `Ready for Release` → `Release in Progress` → `Completed`.
+`PMS::Pipeline::Status::ALL` (in order): `Started` -> `In Review` -> `Ready for Release` -> `Release in Progress` -> `Completed`. (Testing runs orthogonally as a separate single-select field flipped by `request_testing!`, not as a Status value.)
 
 Display names can be overridden in the consuming app via `config.pipeline_statuses`; the constants above remain the internal identifiers.
 
@@ -668,36 +665,36 @@ Display names can be overridden in the consuming app via `config.pipeline_status
 
 ```ruby
 # Add an issue to the pipeline board
-item = PMS::Pipeline.submit!(issue, assignee: current_user.github_login)
+item = PMS::ProjectItem.create!(issue, project_number: PMS::Pipeline.resolve_pipeline_project_number!)
 
 # Forward transitions
-PMS::Pipeline.take!(item)                  # Started
-PMS::Pipeline.mark_in_review!(item)        # In Review
-PMS::Pipeline.request_testing!(item)       # Testing
+PMS::Pipeline.take!(item)                   # Started
+PMS::Pipeline.mark_in_review!(item)         # In Review
+PMS::Pipeline.request_testing!(item)        # flips Testing single-select to active
 PMS::Pipeline.mark_ready_for_release!(item) # Ready for Release
 
 # Deployment-driven transitions
-PMS::Pipeline.start_deployment!(commit_sha: 'abc123…')  # every Ready item whose issue is in the commit → Release in Progress
+PMS::Pipeline.start_deployment!(commit_sha: 'abc123…')  # every Ready item whose issue is in the commit -> Release in Progress
 PMS::Pipeline.complete_deployment!(item, deployment_id: 42)  # Completed (when issue.metadata.auto_complete)
 
 # Remove from pipeline (deletes the project item)
 PMS::Pipeline.remove!(item)
 ```
 
-Forward transitions call `Pipeline.guard_approvals!(issue)`, which raises `PMS::Pipeline::PendingApprovalsError` if the linked issue has un-approved required approvers. Batch/automated transitions (`start_deployment!`, `complete_deployment!`, `remove!`) skip the guard on purpose.
+Forward transitions call `Pipeline.guard_approvals!(issue)`, which raises `PMS::PendingApprovalsError` if the linked issue has un-approved required approvers. Batch/automated transitions (`start_deployment!`, `complete_deployment!`, `remove!`) skip the guard on purpose.
 
 ### Webhook-driven automation
 
 The engine mounts two webhook endpoints when the pipeline is enabled:
 
-- `POST /webhooks/github` — takes GitHub `pull_request` events. On `closed` against a tracked branch, the gem calls `IssueLinker` to extract `#123` references from the PR body and commit messages, then transitions each linked issue (e.g. merged to main → `start_deployment!`).
+- `POST /webhooks/github` — takes GitHub `pull_request` events. On `closed` against a tracked branch, the gem calls `IssueLinker` to extract `#123` references from the PR body and commit messages, then transitions each linked issue (e.g. merged to main -> `start_deployment!`).
 - `POST /webhooks/aws` — takes CodeDeploy/SNS lifecycle events. On a successful deployment, the gem flips matching items to `Completed`.
 
 See `designs/release_cycle/plan.md` for the full design, including the `projects_v2_item` path that fires `Pipeline.take!` when a human drags an item to Started on github.com.
 
 ### "Take" button
 
-The mounted UI exposes a **Take** button on pipeline issues that calls `Pipeline.take!` and assigns the current user. Your app's user-id → GitHub login mapping is provided by `config.github_login_for` (a hash keyed by user id).
+The mounted UI exposes a **Take** button on pipeline issues that calls `Pipeline.take!` and assigns the current user. Your app's user-id -> GitHub login mapping is provided by `config.github_login_for` (a hash keyed by user id).
 
 ## Verify setup
 
@@ -716,7 +713,7 @@ The gem provides test helpers for consuming apps:
 require 'plan_my_stuff/test_helpers'
 
 RSpec.configure do |config|
-  config.include PlanMyStuff::TestHelpers
+  config.include PMS::TestHelpers
 end
 ```
 
@@ -747,7 +744,7 @@ All routes are under the engine's mount point. Each group can be disabled via `c
 | `POST /issues/:issue_id/closure` / `DELETE …/closure` | close / reopen |
 | `POST /issues/:issue_id/waiting` / `DELETE …/waiting` | mark / clear waiting-on-user |
 | `POST /issues/:issue_id/viewers` / `DELETE …/viewers/:id` | add / remove viewer |
-| `POST /issues/:issue_id/take` (pipeline) | Take button → `Pipeline.take!` |
+| `POST /issues/:issue_id/take` (pipeline) | Take button -> `Pipeline.take!` |
 | `POST /issues/:issue_id/comments`, `GET …/comments/:id/edit`, `PATCH …/comments/:id` | create / edit / update comment |
 | `POST /issues/:issue_id/labels` / `DELETE …/labels/:id` | add / remove label |
 | `POST /issues/:issue_id/links` / `DELETE …/links/:id` | link / unlink related issue |
@@ -786,7 +783,7 @@ Every mounted route resolves its controller through `config.controller_for(key)`
 
 ```ruby
 # app/controllers/my_app/issues_controller.rb
-class MyApp::IssuesController < PlanMyStuff::IssuesController
+class MyApp::IssuesController < PMS::IssuesController
   before_action :authenticate_user!
   before_action :authorize_ticket_access
 end
@@ -799,9 +796,9 @@ PlanMyStuff.configure do |config|
 end
 ```
 
-Overridable keys (see `PlanMyStuff::Configuration::DEFAULT_CONTROLLERS`):
+Overridable keys (see `PMS::Configuration::DEFAULT_CONTROLLERS`):
 
-```
+```text
 issues                         issues/closures
 comments                       issues/viewers
 labels                         issues/takes

data/app/controllers/plan_my_stuff/application_controller.rb

@@ -6,6 +6,7 @@ module PlanMyStuff
     helper Rails.application.routes.url_helpers
 
     before_action :authenticate_pms_user!
+    before_action :set_support_user
 
     private
 
@@ -23,8 +24,12 @@ module PlanMyStuff
         instance_exec(&pms_auth) if pms_auth
       end
 
-      # Returns the current user for PMS visibility checks.
-      # Delegates to the consuming app's current_user method.
+      # @return [void]
+      def set_support_user
+        @support_user = support_user?
+      end
+
+      # Returns the current user for PMS visibility checks. Delegates to the consuming app's current_user method.
       #
       # @return [Object, nil]
       #
@@ -34,7 +39,7 @@ module PlanMyStuff
 
       # @return [Boolean]
       def support_user?
-        pms_current_user.present? && PMS::UserResolver.support?(pms_current_user)
+        pms_current_user.present? && PlanMyStuff::UserResolver.support?(pms_current_user)
       end
 
       # Redirects non-support users back with an error.
@@ -49,6 +54,20 @@ module PlanMyStuff
         redirect_to(path)
       end
 
+      # Logs +error+ and invokes the consuming app's +PlanMyStuff.configuration.controller_rescue+ hook so monitoring
+      # can fire even when the rescue swallows the error and redirects to a flash. Wired into every user-facing
+      # controller +rescue+.
+      #
+      # @param error [StandardError]
+      #
+      # @return [void]
+      #
+      def pms_handle_rescue(error)
+        Rails.logger.error("[PlanMyStuff] #{error.class}: #{error.message}")
+        Rails.logger.error(error.backtrace.join("\n")) if error.backtrace
+        PlanMyStuff.configuration.controller_rescue&.call(error)
+      end
+
       # Splits a comma-separated labels string into an array.
       #
       # @param labels_string [String, nil]

data/app/controllers/plan_my_stuff/comments_controller.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 module PlanMyStuff
-  class CommentsController < ApplicationController
+  class CommentsController < PlanMyStuff::ApplicationController
     # POST /issues/:issue_id/comments
     def create
-      @issue = PMS::Issue.find(params[:issue_id].to_i, repo: params[:repo])
+      @issue = PlanMyStuff::Issue.find(params[:issue_id].to_i, repo: params[:repo])
 
-      PMS::Comment.create!(
+      PlanMyStuff::Comment.create!(
         issue: @issue,
         body: comment_params[:body],
         user: pms_current_user,
@@ -16,7 +16,8 @@ module PlanMyStuff
 
       flash[:success] = 'Comment was successfully created.'
       redirect_to(plan_my_stuff.issue_path(@issue.number, repo: @issue.repo.full_name))
-    rescue PMS::LockedIssueError
+    rescue PlanMyStuff::LockedIssueError => e
+      pms_handle_rescue(e)
       flash[:error] = 'This issue is locked; no new comments can be posted.'
       redirect_to(plan_my_stuff.issue_path(@issue.number, repo: @issue.repo.full_name))
     end
@@ -26,8 +27,6 @@ module PlanMyStuff
       load_comment
       return unless @comment
       return redirect_to_issue if issue_body_comment?
-
-      @support_user = support_user?
       return if can_edit?(@comment)
 
       redirect_to_unauthorized(plan_my_stuff.issue_path(@issue.number, repo: @issue.repo.full_name))
@@ -39,7 +38,6 @@ module PlanMyStuff
       return unless @comment
       return redirect_to_issue if issue_body_comment?
 
-      @support_user = support_user?
       unless can_edit?(@comment)
         redirect_to_unauthorized(plan_my_stuff.issue_path(@issue.number, repo: @issue.repo.full_name))
 
@@ -49,13 +47,14 @@ module PlanMyStuff
       update_attrs = { body: comment_params[:body] }
       update_attrs[:visibility] = comment_params[:visibility].to_sym if @support_user && comment_params[:visibility]
 
-      @comment.update!(**update_attrs)
+      @comment.update!(**update_attrs, user: pms_current_user)
 
       flash[:success] = 'Comment was successfully updated.'
       redirect_to(plan_my_stuff.issue_path(@issue.number, repo: @issue.repo.full_name))
-    rescue PMS::StaleObjectError
+    rescue PlanMyStuff::StaleObjectError => e
+      pms_handle_rescue(e)
       flash.now[:error] = 'Comment was modified by someone else. Please review the latest changes and try again.'
-      render(:edit, status: PMS.unprocessable_status)
+      render(:edit, status: PlanMyStuff.unprocessable_status)
     end
 
     private
@@ -70,13 +69,12 @@ module PlanMyStuff
       # @return [void]
       #
       def load_comment
-        @issue = PMS::Issue.find(params[:issue_id].to_i, repo: params[:repo])
-        @comment = PMS::Comment.find(params[:id].to_i, issue: @issue)
+        @issue = PlanMyStuff::Issue.find(params[:issue_id].to_i, repo: params[:repo])
+        @comment = PlanMyStuff::Comment.find(params[:id].to_i, issue: @issue)
       end
 
-      # Returns true if the current user can edit the given comment.
-      # Support users can edit any comment. Regular users can only edit
-      # their own comments.
+      # Returns true if the current user can edit the given comment. Support users can edit any comment. Regular users
+      # can only edit their own comments.
       #
       # @param comment [PlanMyStuff::Comment]
       #
@@ -88,7 +86,7 @@ module PlanMyStuff
         user = pms_current_user
         return false if user.blank?
 
-        comment.metadata.created_by == PMS::UserResolver.user_id(user)
+        comment.metadata.created_by == PlanMyStuff::UserResolver.user_id(user)
       end
 
       # @return [Boolean]