plan_my_stuff 0.6.0 → 0.8.0

data/lib/plan_my_stuff/issue.rb

@@ -23,20 +23,46 @@ module PlanMyStuff
     attribute :labels, default: -> { [] }
     # @return [Time, nil] GitHub's updated_at timestamp
     attribute :updated_at
+    # @return [Time, nil] GitHub's created_at timestamp; settable on unpersisted issues for use with +Issue.import+
+    attribute :created_at
     # @return [Time, nil] GitHub's closed_at timestamp (nil while open)
     attribute :closed_at
-    # @return [Boolean] GitHub's +locked+ flag; +true+ for archived or
-    #   manually-locked issues (no new comments)
+    # @return [Boolean] GitHub's +locked+ flag; +true+ for archived or manually-locked issues (no new comments)
     attribute :locked, :boolean, default: false
     alias locked? locked
     # @return [PlanMyStuff::Repo, nil]
     attribute :repo
     # @return [String, nil] issue body (user-visible content, separate from metadata)
     attribute :body, :string
+    # @return [String, nil] GitHub issue type name (e.g. +"Bug"+, +"Feature"+) or +nil+ when no type is assigned. Read
+    #   from the nested +type.name+ field on the REST response. Settable via the +issue_type:+ kwarg on
+    #   +Issue.create!+ / +Issue.update!+.
+    attribute :issue_type, :string
+
+    # Sentinel default for the +issue_type:+ kwarg on +Issue.update!+. Lets the class method differentiate "kwarg not
+    # provided" (don't touch the type) from "kwarg explicitly set to +nil+" (clear the type). +nil+ alone can't carry
+    # that distinction so we need an object identity check.
+    ISSUE_TYPE_UNCHANGED = Object.new.freeze
+    private_constant :ISSUE_TYPE_UNCHANGED
+
+    # Symbol nicknames for the seven GitHub native issue types the gem knows about. Resolved to canonical names which
+    # then pass through +config.issue_types+ for org-specific renames.
+    ISSUE_TYPE_NICKNAMES = {
+      bug: 'Bug',
+      feature: 'Feature',
+      it_issue: 'IT Issue / Hardware',
+      other: 'Other',
+      performance: 'Performance',
+      question: 'Question',
+      task: 'Task',
+    }.freeze
+    private_constant :ISSUE_TYPE_NICKNAMES
 
     class << self
       # Creates a GitHub issue with PMS metadata embedded in the body.
       #
+      # @raise [PlanMyStuff::ValidationError] when body is blank
+      #
       # @param title [String]
       # @param body [String]
       # @param repo [Symbol, String, nil] defaults to config.default_repo
@@ -46,6 +72,8 @@ module PlanMyStuff
       # @param add_to_project [Boolean, Integer, nil]
       # @param visibility [String] "public" or "internal"
       # @param visibility_allowlist [Array<Integer>] user IDs for internal comment access
+      # @param issue_type [String, nil] GitHub issue type name (e.g. +"Bug"+, +"Feature"+). Must match a type
+      #   configured on the org. +nil+ creates the issue with no type.
       #
       # @return [PlanMyStuff::Issue]
       #
@@ -58,14 +86,17 @@ module PlanMyStuff
         metadata: {},
         add_to_project: nil,
         visibility: 'public',
-        visibility_allowlist: []
+        visibility_allowlist: [],
+        issue_type: nil
       )
-        raise(ValidationError.new('body must be present', field: :body, expected_type: :string)) if body.blank?
+        if body.blank?
+          raise(PlanMyStuff::ValidationError.new('body must be present', field: :body, expected_type: :string))
+        end
 
         client = PlanMyStuff.client
-        resolved_repo = client.resolve_repo(repo)
+        resolved_repo = client.resolve_repo!(repo)
 
-        issue_metadata = IssueMetadata.build(
+        issue_metadata = PlanMyStuff::IssueMetadata.build(
           user: user,
           visibility: visibility,
           custom_fields: metadata,
@@ -73,23 +104,37 @@ module PlanMyStuff
         issue_metadata.visibility_allowlist = Array.wrap(visibility_allowlist)
         issue_metadata.validate_custom_fields!
 
-        serialized_body = MetadataParser.serialize(issue_metadata.to_h, '')
+        serialized_body = PlanMyStuff::MetadataParser.serialize!(issue_metadata.to_h, '')
+
+        resolved_type = resolve_issue_type!(issue_type)
 
         options = {}
-        options[:labels] = labels if labels.any?
+        options[:labels] = labels if labels.present?
+        options[:type] = resolved_type if resolved_type.present?
 
         result = client.rest(:create_issue, resolved_repo, title, serialized_body, **options)
         number = read_field(result, :number)
         store_etag_to_cache(client, resolved_repo, number, result, cache_writer: :write_issue)
 
+        link_body = visible_body_for(number, resolved_repo)
+        if link_body.present?
+          result = client.rest(
+            :update_issue,
+            resolved_repo,
+            number,
+            body: PlanMyStuff::MetadataParser.serialize!(issue_metadata.to_h, link_body),
+          )
+          store_etag_to_cache(client, resolved_repo, number, result, cache_writer: :write_issue)
+        end
+
         issue = find(number, repo: resolved_repo)
 
         if add_to_project.present?
-          project_number = resolve_project_number(add_to_project)
-          ProjectItem.create!(issue, project_number: project_number)
+          project_number = resolve_project_number!(add_to_project)
+          PlanMyStuff::ProjectItem.create!(issue, project_number: project_number)
         end
 
-        Comment.create!(
+        PlanMyStuff::Comment.create!(
           issue: issue,
           body: body,
           user: user,
@@ -122,6 +167,9 @@ module PlanMyStuff
       # @param labels [Array<String>, nil]
       # @param state [Symbol, nil] :open or :closed
       # @param assignees [Array<String>, String, nil] GitHub logins
+      # @param issue_type [String, nil] GitHub issue type name. Pass a String to set, +nil+ to clear, or omit the
+      #   kwarg to leave the current type untouched. (+nil+-vs-omitted is differentiated by the private
+      #   +ISSUE_TYPE_UNCHANGED+ sentinel.)
       #
       # @return [Object]
       #
@@ -133,25 +181,28 @@ module PlanMyStuff
         metadata: nil,
         labels: nil,
         state: nil,
-        assignees: nil
+        assignees: nil,
+        issue_type: ISSUE_TYPE_UNCHANGED
       )
         client = PlanMyStuff.client
-        resolved_repo = client.resolve_repo(repo)
+        resolved_repo = client.resolve_repo!(repo)
 
         options = {}
         options[:title] = title unless title.nil?
         options[:labels] = labels unless labels.nil?
         options[:state] = state.to_s unless state.nil?
         options[:assignees] = Array.wrap(assignees) unless assignees.nil?
+        options[:type] = resolve_issue_type!(issue_type) unless issue_type.equal?(ISSUE_TYPE_UNCHANGED)
 
         case metadata
         when PlanMyStuff::IssueMetadata
           metadata.validate_custom_fields!
-          options[:body] = MetadataParser.serialize(metadata.to_h, '')
+          options[:body] =
+            PlanMyStuff::MetadataParser.serialize!(metadata.to_h, visible_body_for(number, resolved_repo))
         when Hash
           current = client.rest(:issue, resolved_repo, number)
           current_body = current.respond_to?(:body) ? current.body : current[:body]
-          parsed = MetadataParser.parse(current_body)
+          parsed = PlanMyStuff::MetadataParser.parse(current_body)
           existing_metadata = parsed[:metadata]
 
           merged_custom_fields = (existing_metadata[:custom_fields] || {}).merge(metadata[:custom_fields] || {})
@@ -162,10 +213,11 @@ module PlanMyStuff
             merged_custom_fields,
           ).validate!
 
-          options[:body] = MetadataParser.serialize(existing_metadata, '')
+          options[:body] =
+            PlanMyStuff::MetadataParser.serialize!(existing_metadata, visible_body_for(number, resolved_repo))
         end
 
-        update_body_comment(number, resolved_repo, body) if body
+        update_body_comment!(number, resolved_repo, body) if body
 
         return if options.none?
 
@@ -176,6 +228,8 @@ module PlanMyStuff
 
       # Finds a single GitHub issue by number and parses its PMS metadata.
       #
+      # @raise [Octokit::NotFound] when the issue number resolves to a pull request
+      #
       # @param number [Integer]
       # @param repo [Symbol, String, nil] defaults to config.default_repo
       #
@@ -183,7 +237,7 @@ module PlanMyStuff
       #
       def find(number, repo: nil)
         client = PlanMyStuff.client
-        resolved_repo = client.resolve_repo(repo)
+        resolved_repo = client.resolve_repo!(repo)
 
         github_issue =
           fetch_with_etag_cache(
@@ -195,7 +249,14 @@ module PlanMyStuff
             cache_writer: :write_issue,
           )
 
-        if github_issue.respond_to?(:pull_request) && github_issue.pull_request
+        pull_request =
+          if github_issue.respond_to?(:pull_request)
+            github_issue.pull_request
+          elsif github_issue.is_a?(Hash)
+            github_issue[:pull_request] || github_issue['pull_request']
+          end
+
+        if pull_request
           raise(Octokit::NotFound, { method: 'GET', url: "repos/#{resolved_repo}/issues/#{number}" })
         end
 
@@ -214,10 +275,10 @@ module PlanMyStuff
       #
       def list(repo: nil, state: :open, labels: [], page: 1, per_page: 25)
         client = PlanMyStuff.client
-        resolved_repo = client.resolve_repo(repo)
+        resolved_repo = client.resolve_repo!(repo)
 
         params = { state: state.to_s, page: page, per_page: per_page }
-        params[:labels] = labels.sort.join(',') if labels.any?
+        params[:labels] = labels.sort.join(',') if labels.present?
 
         cached = PlanMyStuff::Cache.read_list(:issue, resolved_repo, params)
         request_options = cached ? params.merge(headers: { 'If-None-Match' => cached[:etag] }) : params
@@ -233,8 +294,119 @@ module PlanMyStuff
         filtered.map { |gi| build(gi, repo: resolved_repo) }
       end
 
+      # Submits one or more pre-built payloads to GitHub's "Import Issues" preview endpoint
+      # (+POST /repos/:repo/import/issues+). One request per payload: the endpoint only accepts a single
+      # +{issue:, comments:}+ payload at a time.
+      #
+      # Each payload hash MUST include a +:repo+ key (symbol, string, or +PlanMyStuff::Repo+) and the GitHub-shaped
+      # +:issue+ /+ :comments+ keys; +:repo+ is extracted before the POST. Payloads are passed through to GitHub
+      # unchanged otherwise - callers are responsible for shape, encoding, and any PlanMyStuff metadata they want to
+      # embed.
+      #
+      # The endpoint is async: each response carries an +id+ and +url+ for polling via +Issue.check_import+.
+      #
+      # @raise [ArgumentError] when the import payload is missing :repo
+      #
+      # @param payloads [Array<Hash>, Hash]
+      #
+      # @return [Array<Hash>] one parsed status hash per input payload, in input order
+      #
+      def import!(payloads)
+        client = PlanMyStuff.import_client
+
+        Array.wrap(payloads).map do |payload|
+          repo = payload[:repo] || payload['repo'] || PlanMyStuff.configuration.default_repo
+          raise(ArgumentError, 'import payload must include :repo') if repo.blank?
+
+          body = payload.except(:repo, 'repo')
+          submit_import_request!(client, client.resolve_repo!(repo), body)
+        end
+      end
+
+      # Polls a previously-submitted import for its current status.
+      #
+      # @raise [PlanMyStuff::APIError] when the GitHub API call fails
+      #
+      # @param import_id [Integer] +id+ from the +Issue.import+ response
+      # @param repo [Symbol, String, nil] defaults to config.default_repo
+      #
+      # @return [Hash] parsed status response
+      #
+      def check_import!(import_id, repo: nil)
+        client = PlanMyStuff.import_client
+        resolved_repo = client.resolve_repo!(repo)
+
+        client.octokit.get(
+          "/repos/#{resolved_repo}/import/issues/#{import_id}",
+          accept: 'application/vnd.github.golden-comet-preview+json',
+        )
+      rescue Octokit::ClientError, Octokit::ServerError => e
+        raise(PlanMyStuff::APIError.new(e.message, status: e.respond_to?(:response_status) ? e.response_status : nil))
+      end
+
       private
 
+        # Resolves an +issue_type:+ kwarg to the literal display name GitHub expects. Two stages: a Symbol is first
+        # looked up in the gem-side +ISSUE_TYPE_NICKNAMES+ to get a canonical name; then the canonical (or
+        # directly-provided String) name is passed through +config.issue_types+ for org-specific renames. Missing
+        # entries in +config.issue_types+ fall through unchanged.
+        #
+        # @raise [ArgumentError] if a Symbol isn't a known nickname, or +value+ is not a Symbol/String/nil
+        #
+        # @param value [Symbol, String, nil]
+        #
+        # @return [String, nil]
+        #
+        def resolve_issue_type!(value)
+          return if value.nil?
+
+          canonical =
+            case value
+            when String
+              value
+            when Symbol
+              ISSUE_TYPE_NICKNAMES[value] || raise(
+                ArgumentError,
+                "Unknown issue_type nickname #{value.inspect}; known: #{ISSUE_TYPE_NICKNAMES.keys.inspect}",
+              )
+            else
+              raise(ArgumentError, "issue_type must be a String, Symbol, or nil; got #{value.class}")
+            end
+
+          PlanMyStuff.configuration.issue_types[canonical] || canonical
+        end
+
+        # @raise [PlanMyStuff::APIError] when the GitHub API call fails
+        #
+        # @return [Hash]
+        #
+        def submit_import_request!(client, resolved_repo, payload)
+          client.octokit.post(
+            "/repos/#{resolved_repo}/import/issues",
+            payload.merge(accept: 'application/vnd.github.golden-comet-preview+json'),
+          )
+        rescue Octokit::ClientError, Octokit::ServerError => e
+          raise(PlanMyStuff::APIError.new(e.message, status: e.respond_to?(:response_status) ? e.response_status : nil))
+        end
+
+        # Builds the visible body string written to GitHub for an issue: a markdown link to the consuming-app
+        # per-issue URL (carrying the repo as a +?repo=+ query param so the consuming app knows which repo this issue
+        # lives in), labelled with the GitHub +Org/Repo#number+. Returns +""+ when either +config.issues_url_prefix+
+        # or +number+ is missing.
+        #
+        # @param number [Integer]
+        # @param repo [String] full repo path, e.g. +"BrandsInsurance/Element"+
+        #
+        # @return [String]
+        #
+        def visible_body_for(number, repo)
+          prefix = PlanMyStuff.configuration.issues_url_prefix
+          return '' if prefix.blank? || number.blank?
+
+          url = "#{prefix.to_s.chomp('/')}/#{number}?repo=#{URI.encode_www_form_component(repo)}"
+          "[#{repo}##{number}](#{url})"
+        end
+
         # Hydrates an Issue from a GitHub API response.
         #
         # @param github_issue [Object] Octokit issue response
@@ -248,16 +420,21 @@ module PlanMyStuff
           issue
         end
 
+        # @raise [ArgumentError] when add_to_project is true but no default_project_number is configured
+        #
         # @return [Integer]
-        def resolve_project_number(add_to_project)
+        #
+        def resolve_project_number!(add_to_project)
           return add_to_project unless add_to_project == true
 
           PlanMyStuff.configuration.default_project_number ||
             raise(ArgumentError, 'add_to_project: true requires config.default_project_number to be set')
         end
 
-        # Finds the first PMS comment on an issue and updates its body content,
-        # preserving the comment header and metadata.
+        # Finds the first PMS comment on an issue and updates its body content, preserving the comment header and
+        # metadata.
+        #
+        # @raise [PlanMyStuff::Error] when the issue has no body comment
         #
         # @param number [Integer] issue number
         # @param resolved_repo [String] resolved repo path
@@ -265,7 +442,7 @@ module PlanMyStuff
         #
         # @return [void]
         #
-        def update_body_comment(number, resolved_repo, new_body)
+        def update_body_comment!(number, resolved_repo, new_body)
           issue = find(number, repo: resolved_repo)
           body_comment = issue.body_comment
           raise(PlanMyStuff::Error, "No body comment found on issue ##{number}") if body_comment.nil?
@@ -281,13 +458,11 @@ module PlanMyStuff
 
     # @param value [PlanMyStuff::Repo, Symbol, String, nil]
     def repo=(value)
-      super(value.present? ? PlanMyStuff::Repo.resolve(value) : nil)
+      super(value.present? ? PlanMyStuff::Repo.resolve!(value) : nil)
     end
 
-    # Assigning a new body marks the instance dirty so the next
-    # +save!+ rewrites the backing PMS body comment. Unsaved
-    # assignments are reflected by +#body+ until persisted or
-    # reloaded.
+    # Assigning a new body marks the instance dirty so the next +save!+ rewrites the backing PMS body comment.
+    # Unsaved assignments are reflected by +#body+ until persisted or reloaded.
     #
     # @param value [String]
     #
@@ -298,28 +473,48 @@ module PlanMyStuff
       @body_dirty = true
     end
 
-    # @return [Array<PlanMyStuff::Approval>] all required approvers (pending + approved)
+    # @return [String, nil] per-issue URL in the consuming app (+config.issues_url_prefix+ + +"/"+ + +number+ +
+    #   +"?repo=Org/Repo"+, or +nil+ when either prefix or number is missing). Also rendered as the destination of
+    #   the markdown link in the GitHub issue body.
+    def user_link
+      prefix = PlanMyStuff.configuration.issues_url_prefix
+      return if prefix.blank? || number.blank?
+
+      base = "#{prefix.to_s.chomp('/')}/#{number}"
+      return base if repo.blank?
+
+      "#{base}?repo=#{URI.encode_www_form_component(repo.full_name)}"
+    end
+
+    # @return [Array<PlanMyStuff::Approval>] all required approvers (pending + approved + rejected)
     def approvers
       metadata.approvals
     end
 
-    # @return [Array<PlanMyStuff::Approval>] approvers who have not yet approved
+    # @return [Array<PlanMyStuff::Approval>] approvers who have not yet acted (pending only; rejections are NOT
+    #   pending -- the approver has responded)
     def pending_approvals
       approvers.select(&:pending?)
     end
 
+    # @return [Array<PlanMyStuff::Approval>] approvers who have rejected
+    def rejected_approvals
+      approvers.select(&:rejected?)
+    end
+
     # @return [Boolean] true when at least one approver is required on this issue
     def approvals_required?
-      approvers.any?
+      approvers.present?
     end
 
-    # @return [Boolean] true when approvers are required AND every approver has approved
+    # @return [Boolean] true when approvers are required AND every approver has approved. A single rejection blocks
+    #   this gate until the approver revokes.
     def fully_approved?
-      approvals_required? && pending_approvals.empty?
+      approvals_required? && approvers.all?(&:approved?)
     end
 
-    # Adds user IDs to this issue's visibility allowlist (non-support
-    # users whose ID is in the allowlist can see internal comments).
+    # Adds user IDs to this issue's visibility allowlist (non-support users whose ID is in the allowlist can see
+    # internal comments).
     #
     # Fires +plan_my_stuff.issue.viewers_added+.
     #
@@ -328,9 +523,9 @@ module PlanMyStuff
     #
     # @return [Array<Integer>] the new allowlist
     #
-    def add_viewers(user_ids:, user: nil)
+    def add_viewers!(user_ids:, user: nil)
       ids = Array.wrap(user_ids)
-      modify_allowlist { |allowlist| allowlist | ids }
+      modify_allowlist! { |allowlist| allowlist | ids }
       PlanMyStuff::Notifications.instrument('issue.viewers_added', self, user: user, user_ids: ids)
       metadata.visibility_allowlist
     end
@@ -344,33 +539,30 @@ module PlanMyStuff
     #
     # @return [Array<Integer>] the new allowlist
     #
-    def remove_viewers(user_ids:, user: nil)
+    def remove_viewers!(user_ids:, user: nil)
       ids = Array.wrap(user_ids)
-      modify_allowlist { |allowlist| allowlist - ids }
+      modify_allowlist! { |allowlist| allowlist - ids }
       PlanMyStuff::Notifications.instrument('issue.viewers_removed', self, user: user, user_ids: ids)
       metadata.visibility_allowlist
     end
 
-    # Adds approvers to this issue's required-approvals list. Idempotent:
-    # users already present are no-ops. Only support users may call this.
+    # Adds approvers to this issue's required-approvals list. Idempotent: users already present are no-ops. Only
+    # support users may call this.
     #
-    # Fires +plan_my_stuff.issue.approval_requested+ when any user is
-    # newly added. Also fires +plan_my_stuff.issue.approvals_invalidated+
-    # (+trigger: :approver_added+) when the new approvers flip the issue
+    # Fires +plan_my_stuff.issue.approval_requested+ when any user is newly added. Also fires
+    # +plan_my_stuff.issue.approvals_invalidated+ (+trigger: :approver_added+) when the new approvers flip the issue
     # out of a fully-approved state.
     #
     # @param user_ids [Array<Integer>, Integer]
     # @param user [Object, nil] actor; must be a support user
     #
-    # @raise [PlanMyStuff::AuthorizationError] if +user+ is not support
-    #
     # @return [Array<PlanMyStuff::Approval>] newly-added approvals (empty when all were duplicates)
     #
     def request_approvals!(user_ids:, user: nil)
       guard_support!(user)
       ids = Array.wrap(user_ids).map(&:to_i)
 
-      just_added, was_fully_approved = modify_approvals do |current|
+      just_added, was_fully_approved = modify_approvals! do |current|
         existing_ids = current.map(&:user_id)
         new_ids = ids - existing_ids
         added = new_ids.map { |id| PlanMyStuff::Approval.new(user_id: id, status: 'pending') }
@@ -381,25 +573,21 @@ module PlanMyStuff
       just_added
     end
 
-    # Removes approvers from this issue's required-approvals list. Only
-    # support users may call this. Removing a pending approver may flip
-    # the issue into +fully_approved?+ (fires +all_approved+). Removing
-    # an approved approver fires no events (state does not flip).
-    # Removing the last approver never fires aggregate events (issue no
-    # longer has +approvals_required?+).
+    # Removes approvers from this issue's required-approvals list. Only support users may call this. Removing a
+    # pending approver may flip the issue into +fully_approved?+ (fires +all_approved+). Removing an approved
+    # approver fires no events (state does not flip). Removing the last approver never fires aggregate events (issue
+    # no longer has +approvals_required?+).
     #
     # @param user_ids [Array<Integer>, Integer]
     # @param user [Object, nil] actor; must be a support user
     #
-    # @raise [PlanMyStuff::AuthorizationError] if +user+ is not support
-    #
     # @return [Array<PlanMyStuff::Approval>] removed approval records
     #
     def remove_approvers!(user_ids:, user: nil)
       guard_support!(user)
       ids = Array.wrap(user_ids).map(&:to_i)
 
-      just_removed, was_fully_approved = modify_approvals do |current|
+      just_removed, was_fully_approved = modify_approvals! do |current|
         removed = current.select { |a| ids.include?(a.user_id) }
         [current - removed, removed]
       end
@@ -408,27 +596,27 @@ module PlanMyStuff
       just_removed
     end
 
-    # Flips the caller's approval from +pending+ to +approved+. Only the
-    # approver themselves may call this. Fires
-    # +plan_my_stuff.issue.approval_granted+ and, when this flip
-    # completes the approval set, +plan_my_stuff.issue.all_approved+.
-    #
-    # @param user [Object, Integer] actor; must resolve to an approver currently +pending+
+    # Flips the caller's approval to +approved+ from any other state (+pending+ or +rejected+). Only the approver
+    # themselves may call this. Fires +plan_my_stuff.issue.approval_granted+ and, when this flip completes the
+    # approval set, +plan_my_stuff.issue.all_approved+.
     #
     # @raise [PlanMyStuff::ValidationError] when the caller is not in the approvers list or is already approved
     #
+    # @param user [Object, Integer] actor; must resolve to an approver
+    #
     # @return [PlanMyStuff::Approval] the updated approval
     #
     def approve!(user:)
       actor_id = resolve_actor_id!(user)
 
-      just_approved, was_fully_approved = modify_approvals do |current|
+      just_approved, was_fully_approved = modify_approvals! do |current|
         approval = current.find { |a| a.user_id == actor_id }
         raise(PlanMyStuff::ValidationError, "User #{actor_id} is not in the approvers list") if approval.nil?
-        raise(PlanMyStuff::ValidationError, "User #{actor_id} has already approved") unless approval.pending?
+        raise(PlanMyStuff::ValidationError, "User #{actor_id} has already approved") if approval.approved?
 
         approval.status = 'approved'
         approval.approved_at = Time.current
+        approval.rejected_at = nil
         [current, approval]
       end
 
@@ -436,21 +624,55 @@ module PlanMyStuff
       just_approved
     end
 
-    # Flips an approved record back to +pending+. Approvers may revoke
-    # their own approval; support users may revoke any approver's
-    # approval by passing +target_user_id:+. Non-support callers passing
-    # a +target_user_id:+ that is not their own raise
-    # +AuthorizationError+.
+    # Flips the caller's approval to +rejected+ from any other state (+pending+ or +approved+). Only the approver
+    # themselves may call this. Fires +plan_my_stuff.issue.approval_rejected+ and, when this flip drops the issue
+    # out of +fully_approved?+ (i.e. the caller was the last +approved+ approver),
+    # +plan_my_stuff.issue.approvals_invalidated+ (+trigger: :rejected+).
     #
-    # Fires +plan_my_stuff.issue.approval_revoked+ and, when this flip
-    # drops the issue out of +fully_approved?+,
-    # +plan_my_stuff.issue.approvals_invalidated+ (+trigger: :revoked+).
+    # @raise [PlanMyStuff::ValidationError] when the caller is not in the approvers list or is already rejected
     #
-    # @param user [Object, Integer] the caller
-    # @param target_user_id [Integer, nil] approver whose approval should be revoked; defaults to the caller
+    # @param user [Object, Integer] actor; must resolve to an approver
+    #
+    # @return [PlanMyStuff::Approval] the updated approval
+    #
+    def reject!(user:)
+      actor_id = resolve_actor_id!(user)
+
+      just_rejected, was_fully_approved = modify_approvals! do |current|
+        approval = current.find { |a| a.user_id == actor_id }
+        raise(PlanMyStuff::ValidationError, "User #{actor_id} is not in the approvers list") if approval.nil?
+        raise(PlanMyStuff::ValidationError, "User #{actor_id} has already rejected") if approval.rejected?
+
+        approval.status = 'rejected'
+        approval.rejected_at = Time.current
+        approval.approved_at = nil
+        [current, approval]
+      end
+
+      finish_state_change(
+        :approval_rejected,
+        just_rejected,
+        user: user,
+        was_fully_approved: was_fully_approved,
+        trigger: :rejected,
+      )
+      just_rejected
+    end
+
+    # Flips an approved or rejected record back to +pending+. Approvers may revoke their own response; support users
+    # may revoke any approver's response by passing +target_user_id:+. Non-support callers passing a
+    # +target_user_id:+ that is not their own raise +AuthorizationError+.
+    #
+    # Emits the granular event keyed off the source state: +plan_my_stuff.issue.approval_revoked+ from approved, or
+    # +plan_my_stuff.issue.rejection_revoked+ from rejected. When revoking an approval drops the issue out of
+    # +fully_approved?+, also fires +plan_my_stuff.issue.approvals_invalidated+ (+trigger: :revoked+). Revoking a
+    # rejection cannot change +fully_approved?+ (the issue was already gated), so no aggregate event fires.
     #
     # @raise [PlanMyStuff::AuthorizationError] when a non-support caller targets another user
-    # @raise [PlanMyStuff::ValidationError] when the target is not in the approvers list or is not currently approved
+    # @raise [PlanMyStuff::ValidationError] when the target is not in the approvers list or is currently pending
+    #
+    # @param user [Object, Integer] the caller
+    # @param target_user_id [Integer, nil] approver whose response should be revoked; defaults to the caller
     #
     # @return [PlanMyStuff::Approval] the updated approval
     #
@@ -460,36 +682,39 @@ module PlanMyStuff
       target_id = target_user_id&.to_i || actor_id
 
       if !caller_is_support && target_id != actor_id
-        raise(PlanMyStuff::AuthorizationError, "Only support users may revoke another user's approval")
+        raise(PlanMyStuff::AuthorizationError, "Only support users may revoke another user's response")
       end
 
-      just_revoked, was_fully_approved = modify_approvals do |current|
+      revoked_from = nil
+      just_revoked, was_fully_approved = modify_approvals! do |current|
         approval = current.find { |a| a.user_id == target_id }
         raise(PlanMyStuff::ValidationError, "User #{target_id} is not in the approvers list") if approval.nil?
-        raise(PlanMyStuff::ValidationError, "User #{target_id} is not currently approved") unless approval.approved?
+        if approval.pending?
+          raise(PlanMyStuff::ValidationError, "User #{target_id} has not responded — nothing to revoke")
+        end
 
+        revoked_from = approval.status
         approval.status = 'pending'
         approval.approved_at = nil
+        approval.rejected_at = nil
         [current, approval]
       end
 
+      event = (revoked_from == 'approved') ? :approval_revoked : :rejection_revoked
       finish_state_change(
-        :approval_revoked,
+        event,
         just_revoked,
         user: user,
         was_fully_approved: was_fully_approved,
-        trigger: :revoked,
+        trigger: (event == :approval_revoked) ? :revoked : nil,
       )
       just_revoked
     end
 
-    # Marks the issue as waiting on an end-user reply. Sets
-    # +metadata.waiting_on_user_at+ to now, (re)computes
-    # +metadata.next_reminder_at+, and adds the configured
-    # +waiting_on_user_label+ to the issue. Called from
-    # +Comment.create!+ when a support user posts a comment with
-    # +waiting_on_reply: true+, and from the +Issues::WaitingsController+
-    # toggle.
+    # Marks the issue as waiting on an end-user reply. Sets +metadata.waiting_on_user_at+ to now, (re)computes
+    # +metadata.next_reminder_at+, and adds the configured +waiting_on_user_label+ to the issue. Called from
+    # +Comment.create!+ when a support user posts a comment with +waiting_on_reply: true+, and from the
+    # +Issues::WaitingsController+ toggle.
     #
     # @param user [Object, nil] actor for the label notification event
     #
@@ -500,24 +725,22 @@ module PlanMyStuff
       label = PlanMyStuff.configuration.waiting_on_user_label
 
       PlanMyStuff::Label.ensure!(repo: repo, name: label)
-      PlanMyStuff::Label.add(issue: self, labels: [label], user: user) if labels.exclude?(label)
+      PlanMyStuff::Label.add!(issue: self, labels: [label], user: user) if labels.exclude?(label)
 
       self.class.update!(
         number: number,
         repo: repo,
         metadata: {
-          waiting_on_user_at: now.iso8601,
+          waiting_on_user_at: PlanMyStuff.format_time(now),
           next_reminder_at: format_next_reminder_at(from: now),
         },
       )
       reload
     end
 
-    # Clears the waiting-on-user state: removes the label, clears
-    # +metadata.waiting_on_user_at+, and clears
-    # +metadata.next_reminder_at+ unless a waiting-on-approval timer
-    # is still active. No-ops if the issue is not currently waiting
-    # on a user reply.
+    # Clears the waiting-on-user state: removes the label, clears +metadata.waiting_on_user_at+, and clears
+    # +metadata.next_reminder_at+ unless a waiting-on-approval timer is still active. No-ops if the issue is not
+    # currently waiting on a user reply.
     #
     # @return [self]
     #
@@ -525,25 +748,22 @@ module PlanMyStuff
       label = PlanMyStuff.configuration.waiting_on_user_label
       return self if metadata.waiting_on_user_at.nil? && labels.exclude?(label)
 
-      PlanMyStuff::Label.remove(issue: self, labels: [label]) if labels.include?(label)
+      PlanMyStuff::Label.remove!(issue: self, labels: [label]) if labels.include?(label)
 
       self.class.update!(
         number: number,
         repo: repo,
         metadata: {
           waiting_on_user_at: nil,
-          next_reminder_at: metadata.waiting_on_approval_at ? format_time(metadata.next_reminder_at) : nil,
+          next_reminder_at: metadata.waiting_on_approval_at ? PlanMyStuff.format_time(metadata.next_reminder_at) : nil,
         },
       )
       reload
     end
 
-    # Reopens an issue that was auto-closed by the inactivity sweep,
-    # clears +metadata.closed_by_inactivity+, and emits
-    # +plan_my_stuff.issue.reopened_by_reply+ carrying the reopening
-    # comment. Does not emit the regular +issue.reopened+ event \-
-    # subscribers that specifically care about this flow subscribe
-    # to the dedicated event.
+    # Reopens an issue that was auto-closed by the inactivity sweep, clears +metadata.closed_by_inactivity+, and
+    # emits +plan_my_stuff.issue.reopened_by_reply+ carrying the reopening comment. Does not emit the regular
+    # +issue.reopened+ event \- subscribers that specifically care about this flow subscribe to the dedicated event.
     #
     # @param comment [PlanMyStuff::Comment] the reopening comment
     # @param user [Object, nil] actor for the notification event
@@ -552,7 +772,7 @@ module PlanMyStuff
     #
     def reopen_by_reply!(comment:, user: nil)
       inactive_label = PlanMyStuff.configuration.user_inactive_label
-      PlanMyStuff::Label.remove(issue: self, labels: [inactive_label]) if labels.include?(inactive_label)
+      PlanMyStuff::Label.remove!(issue: self, labels: [inactive_label]) if labels.include?(inactive_label)
 
       self.class.update!(
         number: number,
@@ -571,14 +791,12 @@ module PlanMyStuff
       self
     end
 
-    # Tags the issue with the configured +archived_label+, removes it
-    # from every Projects V2 board it belongs to, locks its
-    # conversation on GitHub, and stamps +metadata.archived_at+.
-    # Emits +plan_my_stuff.issue.archived+ on success.
+    # Tags the issue with the configured +archived_label+, removes it from every Projects V2 board it belongs to,
+    # locks its conversation on GitHub, and stamps +metadata.archived_at+. Emits +plan_my_stuff.issue.archived+ on
+    # success.
     #
-    # No-op (no network calls, no event) when the issue is already
-    # archived (either +metadata.archived_at+ is set or the archived
-    # label is already on the issue).
+    # No-op (no network calls, no event) when the issue is already archived (either +metadata.archived_at+ is set or
+    # the archived label is already on the issue).
     #
     # @param now [Time] clock reference for +metadata.archived_at+
     #
@@ -594,11 +812,11 @@ module PlanMyStuff
       self.class.update!(
         number: number,
         repo: repo,
-        metadata: { archived_at: now.utc.iso8601 },
+        metadata: { archived_at: PlanMyStuff.format_time(now) },
       )
 
       PlanMyStuff::Label.ensure!(repo: repo, name: label)
-      PlanMyStuff::Label.add(issue: self, labels: [label])
+      PlanMyStuff::Label.add!(issue: self, labels: [label])
 
       remove_from_all_projects!
 
@@ -614,13 +832,9 @@ module PlanMyStuff
       self
     end
 
-    # Persists the issue. Creates if new, otherwise performs a full
-    # write: serializes +@metadata+ into the GitHub issue body and
-    # PATCHes title/state/labels. When +#body=+ has been called since
-    # the last load, also rewrites the PMS body comment. Always
-    # reloads afterwards.
-    #
-    # @raise [PlanMyStuff::StaleObjectError] on update if stale
+    # Persists the issue. Creates if new, otherwise performs a full write: serializes +@metadata+ into the GitHub
+    # issue body and PATCHes title/state/labels. When +#body=+ has been called since the last load, also rewrites
+    # the PMS body comment. Always reloads afterwards.
     #
     # @return [self]
     #
@@ -635,6 +849,7 @@ module PlanMyStuff
           metadata: metadata.custom_fields.to_h,
           visibility: metadata.visibility,
           visibility_allowlist: Array.wrap(metadata.visibility_allowlist),
+          issue_type: issue_type,
         )
         hydrate_from_issue(created)
       else
@@ -646,20 +861,16 @@ module PlanMyStuff
       self
     end
 
-    # Applies +attrs+ to this instance in-memory then calls +save!+.
-    # Supports +title:+, +body:+, +state:+, +labels:+, +assignees:+,
-    # and +metadata:+. The +metadata:+ kwarg is a hash whose keys are
-    # merged into the existing +metadata+ (top-level attributes
-    # assigned directly; +:custom_fields+ merged key-by-key).
+    # Applies +attrs+ to this instance in-memory then calls +save!+. Supports +title:+, +body:+, +state:+,
+    # +labels:+, +assignees:+, and +metadata:+. The +metadata:+ kwarg is a hash whose keys are merged into the
+    # existing +metadata+ (top-level attributes assigned directly; +:custom_fields+ merged key-by-key).
     #
     # @param user [Object, nil] actor for notification events
     #
-    # @raise [PlanMyStuff::StaleObjectError] if remote updated_at differs from local
-    #
     # @return [self]
     #
     def update!(user: nil, skip_notification: false, **attrs)
-      apply_update_attrs!(attrs)
+      apply_update_attrs(attrs)
       save!(user: user, skip_notification: skip_notification)
     end
 
@@ -715,9 +926,8 @@ module PlanMyStuff
       pms_comments.find { |c| c.metadata.issue_body? }
     end
 
-    # Returns the issue body content. For PMS issues, this is the body
-    # from the body comment (stripped of its header). Falls back to the
-    # parsed issue body for non-PMS issues.
+    # Returns the issue body content. For PMS issues, this is the body from the body comment (stripped of its
+    # header). Falls back to the parsed issue body for non-PMS issues.
     #
     # @return [String, nil]
     #
@@ -743,13 +953,12 @@ module PlanMyStuff
       if pms_issue?
         metadata.visible_to?(user)
       else
-        UserResolver.support?(UserResolver.resolve(user))
+        PlanMyStuff::UserResolver.support?(PlanMyStuff::UserResolver.resolve(user))
       end
     end
 
-    # Lazy-memoized array of +Issue+ objects for +:related+ links.
-    # Silently drops targets that 404 so a dangling pointer doesn't
-    # break the rest of the list.
+    # Lazy-memoized array of +Issue+ objects for +:related+ links. Silently drops targets that 404 so a dangling
+    # pointer doesn't break the rest of the list.
     #
     # @return [Array<PlanMyStuff::Issue>]
     #
@@ -757,10 +966,8 @@ module PlanMyStuff
       links_cache[:related] ||= fetch_related
     end
 
-    # Adds a +:related+ link to +target+ and, unless this call is
-    # already a reciprocal, mirrors the link back on +target+ so
-    # the pairing is symmetric. Dedups on
-    # +(type, issue_number, repo)+ - re-adding is a no-op.
+    # Adds a +:related+ link to +target+ and, unless this call is already a reciprocal, mirrors the link back on
+    # +target+ so the pairing is symmetric. Dedups on +(type, issue_number, repo)+ - re-adding is a no-op.
     #
     # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
     # @param user [Object, nil] actor for notification events
@@ -769,7 +976,7 @@ module PlanMyStuff
     # @return [PlanMyStuff::Link]
     #
     def add_related!(target, user: nil, reciprocal: false)
-      link = build_link(target, type: :related)
+      link = build_link!(target, type: :related)
       validate_not_self!(link)
 
       existing = current_links
@@ -783,9 +990,8 @@ module PlanMyStuff
       link
     end
 
-    # Removes a +:related+ link to +target+ and, unless this call is
-    # already a reciprocal, mirrors the removal on +target+. No-op
-    # when the link isn't present locally.
+    # Removes a +:related+ link to +target+ and, unless this call is already a reciprocal, mirrors the removal on
+    # +target+. No-op when the link isn't present locally.
     #
     # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
     # @param user [Object, nil]
@@ -794,7 +1000,7 @@ module PlanMyStuff
     # @return [PlanMyStuff::Link]
     #
     def remove_related!(target, user: nil, reciprocal: false)
-      link = build_link(target, type: :related)
+      link = build_link!(target, type: :related)
       validate_not_self!(link)
 
       existing = current_links
@@ -808,8 +1014,7 @@ module PlanMyStuff
       link
     end
 
-    # Lazy-memoized parent issue via GitHub's native sub-issues API.
-    # GitHub enforces at most one parent per issue.
+    # Lazy-memoized parent issue via GitHub's native sub-issues API. GitHub enforces at most one parent per issue.
     #
     # @return [PlanMyStuff::Issue, nil]
     #
@@ -827,8 +1032,7 @@ module PlanMyStuff
       links_cache[:sub_tickets] ||= fetch_sub_tickets
     end
 
-    # Adds +target+ as a sub-issue of self via
-    # +POST /issues/{number}/sub_issues+. Native GitHub action;
+    # Adds +target+ as a sub-issue of self via +POST /issues/{number}/sub_issues+. Native GitHub action;
     # notifications are handled by GitHub itself.
     #
     # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
@@ -839,8 +1043,7 @@ module PlanMyStuff
       mutate_sub_issue!(target, method: :post, path: sub_issues_path)
     end
 
-    # Removes +target+ as a sub-issue of self via
-    # +DELETE /issues/{number}/sub_issue+ (singular).
+    # Removes +target+ as a sub-issue of self via +DELETE /issues/{number}/sub_issue+ (singular).
     #
     # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
     #
@@ -850,9 +1053,8 @@ module PlanMyStuff
       mutate_sub_issue!(target, method: :delete, path: remove_sub_issue_path)
     end
 
-    # Makes +target+ the parent of self. If self already has a parent,
-    # it is detached first. Returns a +Link+ describing the new
-    # +:parent+ relationship.
+    # Makes +target+ the parent of self. If self already has a parent, it is detached first. Returns a +Link+
+    # describing the new +:parent+ relationship.
     #
     # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
     #
@@ -865,11 +1067,11 @@ module PlanMyStuff
       target_issue.add_sub_issue!(self)
       invalidate_links_cache!
 
-      build_link(target_issue, type: :parent)
+      build_link!(target_issue, type: :parent)
     end
 
-    # Detaches self from its current parent, if any. Returns the
-    # +Link+ that was removed, or nil when there was no parent.
+    # Detaches self from its current parent, if any. Returns the +Link+ that was removed, or nil when there was no
+    # parent.
     #
     # @return [PlanMyStuff::Link, nil]
     #
@@ -880,12 +1082,11 @@ module PlanMyStuff
       current.remove_sub_issue!(self)
       invalidate_links_cache!
 
-      build_link(current, type: :parent)
+      build_link!(current, type: :parent)
     end
 
-    # Lazy-memoized issues that block self (i.e. self is blocked by
-    # each returned issue) via GitHub's native issue-dependency REST
-    # API.
+    # Lazy-memoized issues that block self (i.e. self is blocked by each returned issue) via GitHub's native
+    # issue-dependency REST API.
     #
     # @return [Array<PlanMyStuff::Issue>]
     #
@@ -901,15 +1102,14 @@ module PlanMyStuff
       links_cache[:blocking] ||= fetch_dependencies('blocking')
     end
 
-    # Records that +target+ blocks self. Native GitHub action;
-    # notifications are handled by GitHub itself.
+    # Records that +target+ blocks self. Native GitHub action; notifications are handled by GitHub itself.
     #
     # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
     #
     # @return [PlanMyStuff::Link]
     #
     def add_blocker!(target)
-      link = build_link(target, type: :blocked_by)
+      link = build_link!(target, type: :blocked_by)
       validate_not_self!(link)
 
       target_issue = resolve_target_issue(target, type: :blocked_by)
@@ -929,7 +1129,7 @@ module PlanMyStuff
     # @return [PlanMyStuff::Link]
     #
     def remove_blocker!(target)
-      link = build_link(target, type: :blocked_by)
+      link = build_link!(target, type: :blocked_by)
       validate_not_self!(link)
 
       target_issue = resolve_target_issue(target, type: :blocked_by)
@@ -941,9 +1141,8 @@ module PlanMyStuff
       link
     end
 
-    # Lazy-memoized issue that self was marked as duplicate of, via
-    # GitHub's native close-as-duplicate. Returns nil for issues that
-    # are open or closed for other reasons.
+    # Lazy-memoized issue that self was marked as duplicate of, via GitHub's native close-as-duplicate. Returns nil
+    # for issues that are open or closed for other reasons.
     #
     # @return [PlanMyStuff::Issue, nil]
     #
@@ -953,9 +1152,8 @@ module PlanMyStuff
       links_cache[:duplicate_of] = fetch_duplicate_of
     end
 
-    # Closes self as a duplicate of +target+ via GitHub's native
-    # close-as-duplicate, carrying over viewers, assignees, and a
-    # back-pointer comment on the target.
+    # Closes self as a duplicate of +target+ via GitHub's native close-as-duplicate, carrying over viewers,
+    # assignees, and a back-pointer comment on the target.
     #
     # Side effects, in order:
     # 1. Resolves +target+; raises +ValidationError+ if missing.
@@ -968,8 +1166,9 @@ module PlanMyStuff
     # 7. Reloads self; invalidates link caches.
     # 8. Fires +plan_my_stuff.issue.marked_duplicate+.
     #
-    # Partial failures are not rolled back - GitHub retains whatever
-    # side effects succeeded before the failing step.
+    # Partial failures are not rolled back - GitHub retains whatever side effects succeeded before the failing step.
+    #
+    # @raise [PlanMyStuff::ValidationError] when the issue is already closed
     #
     # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
     # @param user [Object, nil] actor for notification + comment
@@ -980,20 +1179,19 @@ module PlanMyStuff
       raise(PlanMyStuff::ValidationError, 'Cannot mark a closed issue as duplicate') if state == 'closed'
 
       target_issue = resolve_duplicate_target!(target)
-      merge_visibility_allowlist_onto(target_issue)
-      merge_assignees_onto(target_issue)
-      post_duplicate_back_pointer(target_issue, user: user)
+      merge_visibility_allowlist_onto!(target_issue)
+      merge_assignees_onto!(target_issue)
+      post_duplicate_back_pointer!(target_issue, user: user)
       close_as_duplicate!(target_issue)
 
       reload
       invalidate_links_cache!
       PlanMyStuff::Notifications.instrument('issue.marked_duplicate', self, target: target_issue, user: user)
 
-      build_link(target_issue, type: :duplicate_of)
+      build_link!(target_issue, type: :duplicate_of)
     end
 
-    # GitHub GraphQL node ID (required for native sub-issue mutations).
-    # Read from the hydrated REST response.
+    # GitHub GraphQL node ID (required for native sub-issue mutations). Read from the hydrated REST response.
     #
     # @return [String, nil]
     #
@@ -1001,8 +1199,8 @@ module PlanMyStuff
       safe_read_field(github_response, :node_id)
     end
 
-    # GitHub database ID (required for the REST issue-dependency API,
-    # which takes integer issue_id rather than issue number).
+    # GitHub database ID (required for the REST issue-dependency API, which takes integer issue_id rather than issue
+    # number).
     #
     # @return [Integer, nil]
     #
@@ -1012,16 +1210,15 @@ module PlanMyStuff
 
     private
 
-      # Yields +self.metadata.visibility_allowlist+ for modification,
-      # persists the updated allowlist via the class-level +update!+,
-      # and reloads +self+ so subsequent reads see the fresh state.
+      # Yields +self.metadata.visibility_allowlist+ for modification, persists the updated allowlist via the
+      # class-level +update!+, and reloads +self+ so subsequent reads see the fresh state.
       #
       # @yieldparam allowlist [Array<Integer>]
       # @yieldreturn [Array<Integer>] the new allowlist
       #
       # @return [void]
       #
-      def modify_allowlist
+      def modify_allowlist!
         new_allowlist = yield(Array.wrap(metadata.visibility_allowlist))
         self.class.update!(
           number: number,
@@ -1031,16 +1228,15 @@ module PlanMyStuff
         reload
       end
 
-      # Captures +fully_approved?+ state, yields the current approvals
-      # (deep-copied) for mutation, persists the new list to GitHub, and
-      # reloads +self+. Returns +[extra, was_fully_approved]+.
+      # Captures +fully_approved?+ state, yields the current approvals (deep-copied) for mutation, persists the new
+      # list to GitHub, and reloads +self+. Returns +[extra, was_fully_approved]+.
       #
       # @yieldparam current [Array<PlanMyStuff::Approval>] deep-copied approvals
       # @yieldreturn [Array(Array<PlanMyStuff::Approval>, Object)] +[new_list, extra]+
       #
       # @return [Array(Object, Boolean)]
       #
-      def modify_approvals
+      def modify_approvals!
         was_fully_approved = fully_approved?
         was_pending_count = metadata.approvals.count(&:pending?)
         current = metadata.approvals.map { |a| PlanMyStuff::Approval.new(a.attributes) }
@@ -1054,16 +1250,14 @@ module PlanMyStuff
         self.class.update!(number: number, repo: repo, metadata: metadata_updates)
         reload
 
-        sync_waiting_on_approval_label(was_pending_count, new_pending_count)
+        sync_waiting_on_approval_label!(was_pending_count, new_pending_count)
 
         [extra, was_fully_approved]
       end
 
-      # Computes the metadata delta for the waiting-on-approval timer
-      # based on the change in pending-approval count. The timer resets
-      # only when pending count goes UP (add approver, revoke-to-pending)
-      # so that remaining pending approvers keep their original schedule
-      # when a peer approves. Drop-to-zero clears the timer entirely.
+      # Computes the metadata delta for the waiting-on-approval timer based on the change in pending-approval count.
+      # The timer resets only when pending count goes UP (add approver, revoke-to-pending) so that remaining pending
+      # approvers keep their original schedule when a peer approves. Drop-to-zero clears the timer entirely.
       #
       # @param was [Integer] pending count before the mutation
       # @param now [Integer] pending count after the mutation
@@ -1074,41 +1268,41 @@ module PlanMyStuff
         if now > was
           ts = Time.now.utc
           {
-            waiting_on_approval_at: ts.iso8601,
+            waiting_on_approval_at: PlanMyStuff.format_time(ts),
             next_reminder_at: format_next_reminder_at(from: ts),
           }
         elsif now.zero? && was.positive?
           {
             waiting_on_approval_at: nil,
-            next_reminder_at: metadata.waiting_on_user_at ? format_time(metadata.next_reminder_at) : nil,
+            next_reminder_at: metadata.waiting_on_user_at ? PlanMyStuff.format_time(metadata.next_reminder_at) : nil,
           }
         else
           {}
         end
       end
 
-      # Adds or removes the configured waiting-on-approval label when the
-      # pending-approval count crosses the zero boundary. Mutations that
-      # stay on the same side of zero leave the label untouched.
+      # Adds or removes the configured waiting-on-approval label when the pending-approval count crosses the zero
+      # boundary. Mutations that stay on the same side of zero leave the label untouched.
       #
       # @param was [Integer] pending count before the mutation
       # @param now [Integer] pending count after the mutation
       #
       # @return [void]
       #
-      def sync_waiting_on_approval_label(was, now)
+      def sync_waiting_on_approval_label!(was, now)
         label = PlanMyStuff.configuration.waiting_on_approval_label
 
         if now.positive? && was.zero?
           PlanMyStuff::Label.ensure!(repo: repo, name: label)
-          PlanMyStuff::Label.add(issue: self, labels: [label]) if labels.exclude?(label)
+          PlanMyStuff::Label.add!(issue: self, labels: [label]) if labels.exclude?(label)
         elsif now.zero? && was.positive?
-          PlanMyStuff::Label.remove(issue: self, labels: [label]) if labels.include?(label)
+          PlanMyStuff::Label.remove!(issue: self, labels: [label]) if labels.include?(label)
         end
       end
 
-      # Raises +AuthorizationError+ unless +user+ resolves to a support
-      # user. +nil+ user is treated as unauthorized.
+      # Ensures +user+ resolves to a support user. +nil+ user is treated as unauthorized.
+      #
+      # @raise [PlanMyStuff::AuthorizationError] when the actor is not a support user
       #
       # @param user [Object, Integer, nil]
       #
@@ -1121,8 +1315,9 @@ module PlanMyStuff
         raise(PlanMyStuff::AuthorizationError, 'Only support users may manage approvers')
       end
 
-      # Resolves +user+ to an integer user_id. Raises +ArgumentError+
-      # when +user+ is +nil+.
+      # Resolves +user+ to an integer user_id.
+      #
+      # @raise [ArgumentError] when user is nil
       #
       # @param user [Object, Integer]
       #
@@ -1135,9 +1330,8 @@ module PlanMyStuff
         PlanMyStuff::UserResolver.user_id(resolved)
       end
 
-      # Fires +approval_requested+ (when any users were newly added) and,
-      # if the aggregate state flipped out of fully-approved, the
-      # +approvals_invalidated+ follow-up.
+      # Fires +approval_requested+ (when any users were newly added) and, if the aggregate state flipped out of
+      # fully-approved, the +approvals_invalidated+ follow-up.
       #
       # @param added [Array<PlanMyStuff::Approval>]
       # @param user [Object, nil]
@@ -1157,8 +1351,8 @@ module PlanMyStuff
         emit_aggregate_events(was_fully_approved: was_fully_approved, trigger: :approver_added, user: user)
       end
 
-      # Fires the granular event (+approval_granted+ / +approval_revoked+)
-      # then any aggregate follow-up triggered by the state flip.
+      # Fires the granular event (+approval_granted+ / +approval_revoked+) then any aggregate follow-up triggered
+      # by the state flip.
       #
       # @param event [Symbol] +:approval_granted+ or +:approval_revoked+
       # @param approval [PlanMyStuff::Approval]
@@ -1178,10 +1372,9 @@ module PlanMyStuff
         emit_aggregate_events(was_fully_approved: was_fully_approved, trigger: trigger, user: user)
       end
 
-      # Fires +all_approved+ or +approvals_invalidated+ based on whether
-      # +fully_approved?+ flipped. Suppresses +approvals_invalidated+
-      # when the issue no longer has any approvers required (dropping
-      # the list to empty is not an invalidation).
+      # Fires +all_approved+ or +approvals_invalidated+ based on whether +fully_approved?+ flipped. Suppresses
+      # +approvals_invalidated+ when the issue no longer has any approvers required (dropping the list to empty is
+      # not an invalidation).
       #
       # @param was_fully_approved [Boolean]
       # @param trigger [Symbol, nil]
@@ -1218,13 +1411,15 @@ module PlanMyStuff
         self.state = read_field(github_issue, :state)
         self.raw_body = read_field(github_issue, :body) || ''
         self.updated_at = parse_github_time(safe_read_field(github_issue, :updated_at))
+        self.created_at = parse_github_time(safe_read_field(github_issue, :created_at))
         self.closed_at = parse_github_time(safe_read_field(github_issue, :closed_at))
         self.locked = safe_read_field(github_issue, :locked) || false
         self.labels = extract_labels(github_issue)
+        self.issue_type = extract_issue_type(github_issue)
         self.repo = repo
 
-        parsed = MetadataParser.parse(raw_body)
-        self.metadata = IssueMetadata.from_hash(parsed[:metadata])
+        parsed = PlanMyStuff::MetadataParser.parse(raw_body)
+        self.metadata = PlanMyStuff::IssueMetadata.from_hash(parsed[:metadata])
         self.body = parsed[:body]
         @body_dirty = false
         persisted!
@@ -1246,10 +1441,12 @@ module PlanMyStuff
         self.body = other.attributes['body']
         @body_dirty = false
         self.raw_body = other.raw_body
+        self.created_at = other.created_at
         self.updated_at = other.updated_at
         self.closed_at = other.closed_at
         self.locked = other.locked
         self.labels = other.labels
+        self.issue_type = other.issue_type
         self.repo = other.repo
         self.metadata = other.metadata
         persisted!
@@ -1257,10 +1454,8 @@ module PlanMyStuff
         invalidate_links_cache!
       end
 
-      # Formats the next reminder time as an ISO 8601 UTC string, using
-      # per-issue +metadata.reminder_days+ when set or
-      # +config.reminder_days+ otherwise. Returns +nil+ when the
-      # effective schedule is empty.
+      # Formats the next reminder time as an ISO 8601 UTC string, using per-issue +metadata.reminder_days+ when set
+      # or +config.reminder_days+ otherwise. Returns +nil+ when the effective schedule is empty.
       #
       # @param from [Time] baseline timestamp
       #
@@ -1270,25 +1465,11 @@ module PlanMyStuff
         days = metadata.reminder_days.presence || PlanMyStuff.configuration.reminder_days
         return if days.empty?
 
-        (from + days.first.days).utc.iso8601
+        PlanMyStuff.format_time(from + days.first.days)
       end
 
-      # Formats a +Time+ as an ISO 8601 UTC string, or +nil+ when the
-      # input is nil.
-      #
-      # @param time [Time, nil]
-      #
-      # @return [String, nil]
-      #
-      def format_time(time)
-        return if time.nil?
-
-        time.utc.iso8601
-      end
-
-      # Fires the appropriate notification event for an update: +issue.closed+
-      # or +issue.reopened+ on a state transition, otherwise +issue.updated+
-      # with the captured dirty-tracking diff.
+      # Fires the appropriate notification event for an update: +issue.closed+ or +issue.reopened+ on a state
+      # transition, otherwise +issue.updated+ with the captured dirty-tracking diff.
       #
       # @param captured [Hash] +ActiveModel::Dirty+ changes captured before +persist_update!+
       # @param user [Object, nil]
@@ -1306,17 +1487,15 @@ module PlanMyStuff
         end
       end
 
-      # When an issue is transitioning from open to closed, strips both
-      # waiting labels from the outgoing labels array and clears the
-      # waiting-related timestamps on +metadata+ so a single save writes
-      # both state change and cleanup. No-op for any other transition.
+      # When an issue is transitioning from open to closed, strips both waiting labels from the outgoing labels
+      # array and clears the waiting-related timestamps on +metadata+ so a single save writes both state change and
+      # cleanup. No-op for any other transition.
       #
-      # @param attrs [Hash] the kwargs hash being assembled for
-      #   +Issue.update!+; mutated in place
+      # @param attrs [Hash] the kwargs hash being assembled for +Issue.update!+; mutated in place
       #
       # @return [void]
       #
-      def clear_waiting_state_on_close!(attrs)
+      def clear_waiting_state_on_close(attrs)
         return unless state_changed?
         return unless state_was == 'open'
         return unless state == 'closed'
@@ -1334,17 +1513,15 @@ module PlanMyStuff
         metadata.next_reminder_at = nil
       end
 
-      # When an inactivity-closed issue is being reopened, strips the
-      # +user_inactive_label+ from the outgoing labels and clears
-      # +metadata.closed_by_inactivity+ so the save writes both. No-op
-      # for any other transition or for reopens of non-inactive closes.
+      # When an inactivity-closed issue is being reopened, strips the +user_inactive_label+ from the outgoing labels
+      # and clears +metadata.closed_by_inactivity+ so the save writes both. No-op for any other transition or for
+      # reopens of non-inactive closes.
       #
-      # @param attrs [Hash] the kwargs hash being assembled for
-      #   +Issue.update!+; mutated in place
+      # @param attrs [Hash] the kwargs hash being assembled for +Issue.update!+; mutated in place
       #
       # @return [void]
       #
-      def clear_inactivity_state_on_reopen!(attrs)
+      def clear_inactivity_state_on_reopen(attrs)
         return unless state_changed?
         return unless state_was == 'closed'
         return unless state == 'open'
@@ -1354,14 +1531,10 @@ module PlanMyStuff
         metadata.closed_by_inactivity = false
       end
 
-      # Full-write persistence path for an already-persisted issue.
-      # Delegates to +Issue.update!+ passing the full in-memory state
-      # (title/state/labels plus the current +metadata+ object so the
-      # class method serializes it authoritatively). Only passes
-      # +body:+ when +@body_dirty+, so the PMS body comment is
-      # rewritten exactly when +#body=+ has been called since load.
-      #
-      # @raise [PlanMyStuff::StaleObjectError]
+      # Full-write persistence path for an already-persisted issue. Delegates to +Issue.update!+ passing the full
+      # in-memory state (title/state/labels plus the current +metadata+ object so the class method serializes it
+      # authoritatively). Only passes +body:+ when +@body_dirty+, so the PMS body comment is rewritten exactly when
+      # +#body=+ has been called since load.
       #
       # @return [void]
       #
@@ -1378,9 +1551,10 @@ module PlanMyStuff
         }
         attrs[:body] = body if @body_dirty
         attrs[:assignees] = @pending_assignees unless @pending_assignees.nil?
+        attrs[:issue_type] = issue_type if issue_type_changed?
 
-        clear_waiting_state_on_close!(attrs)
-        clear_inactivity_state_on_reopen!(attrs)
+        clear_waiting_state_on_close(attrs)
+        clear_inactivity_state_on_reopen(attrs)
 
         self.class.update!(**attrs)
 
@@ -1389,25 +1563,24 @@ module PlanMyStuff
         reload
       end
 
-      # Applies in-memory updates from an +update!+ kwargs hash.
-      # Top-level scalars go through their setters so +@body_dirty+
-      # and friends stay in sync; +metadata:+ is merged into
-      # +@metadata+ (top-level attrs assigned directly, custom_fields
-      # merged key-by-key).
+      # Applies in-memory updates from an +update!+ kwargs hash. Top-level scalars go through their setters so
+      # +@body_dirty+ and friends stay in sync; +metadata:+ is merged into +@metadata+ (top-level attrs assigned
+      # directly, custom_fields merged key-by-key).
       #
       # @return [void]
       #
-      def apply_update_attrs!(attrs)
+      def apply_update_attrs(attrs)
         self.title = attrs[:title] if attrs.key?(:title)
         self.state = attrs[:state].to_s if attrs.key?(:state)
         self.labels = attrs[:labels] if attrs.key?(:labels)
         self.body = attrs[:body] if attrs.key?(:body)
+        self.issue_type = attrs[:issue_type] if attrs.key?(:issue_type)
         @pending_assignees = attrs[:assignees] if attrs.key?(:assignees)
-        apply_metadata_attrs!(attrs[:metadata]) if attrs.key?(:metadata)
+        apply_metadata_attrs(attrs[:metadata]) if attrs.key?(:metadata)
       end
 
       # @return [void]
-      def apply_metadata_attrs!(md_hash)
+      def apply_metadata_attrs(md_hash)
         return if md_hash.nil?
 
         md_hash.each do |key, value|
@@ -1419,8 +1592,7 @@ module PlanMyStuff
         end
       end
 
-      # Raises StaleObjectError if the remote issue has been modified
-      # since this instance was loaded.
+      # Raises StaleObjectError if the remote issue has been modified since this instance was loaded.
       #
       # @raise [PlanMyStuff::StaleObjectError]
       #
@@ -1437,11 +1609,13 @@ module PlanMyStuff
         return if remote_time.nil?
         return if local_time && remote_time.to_i == local_time.to_i
 
-        raise(StaleObjectError.new(
-          "Issue ##{number} has been modified remotely",
-          local_updated_at: local_time,
-          remote_updated_at: remote_time,
-        ))
+        raise(
+          PlanMyStuff::StaleObjectError.new(
+            "Issue ##{number} has been modified remotely",
+            local_updated_at: local_time,
+            remote_updated_at: remote_time,
+          ),
+        )
       end
 
       # @return [Array<String>]
@@ -1450,6 +1624,18 @@ module PlanMyStuff
         raw.map { |label| label_name(label) }
       end
 
+      # Reads the +type.name+ from a REST issue payload. GitHub returns +"type"+ as a nested object (or +nil+) on
+      # every issue response, so we descend into it for the human-readable name.
+      #
+      # @return [String, nil]
+      #
+      def extract_issue_type(github_issue)
+        raw = safe_read_field(github_issue, :type)
+        return if raw.nil?
+
+        safe_read_field(raw, :name)
+      end
+
       # @return [String]
       def label_name(label)
         return label.name if label.respond_to?(:name)
@@ -1460,7 +1646,7 @@ module PlanMyStuff
 
       # @return [Array<PlanMyStuff::Comment>]
       def load_comments
-        Comment.list(issue: self)
+        PlanMyStuff::Comment.list(issue: self)
       end
 
       # @return [Hash{Symbol => Array}]
@@ -1468,8 +1654,7 @@ module PlanMyStuff
         @links_cache ||= {}
       end
 
-      # Clears all memoized link readers. Called from +#hydrate_from_github+
-      # and after any successful write.
+      # Clears all memoized link readers. Called from +#hydrate_from_github+ and after any successful write.
       #
       # @return [void]
       #
@@ -1477,16 +1662,16 @@ module PlanMyStuff
         @links_cache = {}
       end
 
-      # Normalizes +target+ to a +PlanMyStuff::Link+ with the source
-      # repo defaulting to self's repo.
+      # Normalizes +target+ to a +PlanMyStuff::Link+ with the source repo defaulting to self's repo.
       #
       # @return [PlanMyStuff::Link]
       #
-      def build_link(target, type:)
-        PlanMyStuff::Link.build(target, type: type, source_repo: repo&.full_name)
+      def build_link!(target, type:)
+        PlanMyStuff::Link.build!(target, type: type, source_repo: repo&.full_name)
       end
 
-      # @raise [PlanMyStuff::ValidationError]
+      # @raise [PlanMyStuff::ValidationError] when target is the same issue (self-link)
+      #
       # @return [void]
       #
       def validate_not_self!(link)
@@ -1496,8 +1681,7 @@ module PlanMyStuff
         raise(PlanMyStuff::ValidationError, 'Cannot link an issue to itself')
       end
 
-      # Reads +metadata.links+ and coerces any legacy hash entries to
-      # +Link+ instances. Invalid entries are dropped.
+      # Reads +metadata.links+ and coerces any legacy hash entries to +Link+ instances. Invalid entries are dropped.
       #
       # @return [Array<PlanMyStuff::Link>]
       #
@@ -1505,14 +1689,13 @@ module PlanMyStuff
         metadata.links.filter_map do |entry|
           next entry if entry.is_a?(PlanMyStuff::Link)
 
-          PlanMyStuff::Link.build(entry)
+          PlanMyStuff::Link.build!(entry)
         rescue ActiveModel::ValidationError, ArgumentError
           next
         end
       end
 
-      # Writes the given link array back to GitHub via
-      # +Issue.update!+ and updates local metadata so subsequent
+      # Writes the given link array back to GitHub via +Issue.update!+ and updates local metadata so subsequent
       # in-memory reads see the change without a +reload+.
       #
       # @param new_links [Array<PlanMyStuff::Link>]
@@ -1529,9 +1712,8 @@ module PlanMyStuff
         invalidate_links_cache!
       end
 
-      # Walks every Projects V2 board this issue sits on and deletes the
-      # corresponding item. Paginates via +LIST_ISSUE_PROJECT_ITEMS+ with
-      # a safety cap to avoid runaway loops. Delete failures propagate.
+      # Walks every Projects V2 board this issue sits on and deletes the corresponding item. Paginates via
+      # +LIST_ISSUE_PROJECT_ITEMS+ with a safety cap to avoid runaway loops. Delete failures propagate.
       #
       # @return [void]
       #
@@ -1551,7 +1733,7 @@ module PlanMyStuff
           nodes = Array.wrap(connection[:nodes])
 
           nodes.each do |node|
-            PlanMyStuff::ProjectItem.delete_item(
+            PlanMyStuff::ProjectItem.delete_item!(
               item_id: node[:id],
               project_number: node.dig(:project, :number),
             )
@@ -1564,9 +1746,8 @@ module PlanMyStuff
         end
       end
 
-      # Attempts the reciprocal write on +link+'s target. On failure,
-      # fires +plan_my_stuff.issue.link_reciprocal_failed+ so the
-      # consuming app can surface the half-written pairing.
+      # Attempts the reciprocal write on +link+'s target. On failure, fires
+      # +plan_my_stuff.issue.link_reciprocal_failed+ so the consuming app can surface the half-written pairing.
       #
       # @param link [PlanMyStuff::Link]
       # @param user [Object, nil]
@@ -1621,27 +1802,26 @@ module PlanMyStuff
         end
       end
 
-      # Normalizes +target+ to a fully-hydrated +Issue+ (fetching when
-      # we only have a +Link+ or hash). Used by +set_parent!+ /
-      # +remove_parent!+ to invert the call back through
-      # +#add_sub_issue!+ / +#remove_sub_issue!+ on the parent side.
+      # Normalizes +target+ to a fully-hydrated +Issue+ (fetching when we only have a +Link+ or hash). Used by
+      # +set_parent!+ / +remove_parent!+ to invert the call back through +#add_sub_issue!+ / +#remove_sub_issue!+ on
+      # the parent side.
       #
       # @return [PlanMyStuff::Issue]
       #
       def resolve_target_issue(target, type:)
         return target if target.is_a?(PlanMyStuff::Issue)
 
-        link = build_link(target, type: type)
+        link = build_link!(target, type: type)
         PlanMyStuff::Issue.find(link.issue_number, repo: link.repo)
       end
 
-      # Shared path for add_sub_issue! / remove_sub_issue!. Builds the
-      # link, resolves the target, runs the mutation, busts caches.
+      # Shared path for add_sub_issue! / remove_sub_issue!. Builds the link, resolves the target, runs the
+      # mutation, busts caches.
       #
       # @return [PlanMyStuff::Link]
       #
       def mutate_sub_issue!(target, method:, path:)
-        link = build_link(target, type: :sub_ticket)
+        link = build_link!(target, type: :sub_ticket)
         validate_not_self!(link)
 
         target_issue = resolve_target_issue(target, type: :sub_ticket)
@@ -1664,8 +1844,7 @@ module PlanMyStuff
         "/repos/#{repo.organization}/#{repo.name}/issues/#{number}/sub_issues"
       end
 
-      # GitHub's REMOVE endpoint is +/sub_issue+ (singular), distinct
-      # from the list/add path +/sub_issues+ (plural).
+      # GitHub's REMOVE endpoint is +/sub_issue+ (singular), distinct from the list/add path +/sub_issues+ (plural).
       #
       # @return [String]
       #
@@ -1673,10 +1852,9 @@ module PlanMyStuff
         "/repos/#{repo.organization}/#{repo.name}/issues/#{number}/sub_issue"
       end
 
-      # Fetches one side of the native issue-dependency graph for self
-      # (+blocked_by+ or +blocking+) via REST. Response is an array of
-      # Issue objects; we map through +Issue.find+ to get fully hydrated
-      # instances (the dependency endpoint returns a slim projection).
+      # Fetches one side of the native issue-dependency graph for self (+blocked_by+ or +blocking+) via REST.
+      # Response is an array of Issue objects; we map through +Issue.find+ to get fully hydrated instances (the
+      # dependency endpoint returns a slim projection).
       #
       # @param side [String] "blocked_by" or "blocking"
       #
@@ -1722,8 +1900,9 @@ module PlanMyStuff
         PlanMyStuff::Issue.find(the_dupe[:number], repo: the_dupe.dig(:repository, :nameWithOwner))
       end
 
-      # Resolves +target+ to an +Issue+ and raises +ValidationError+
-      # when the target cannot be found.
+      # Resolves +target+ to an +Issue+.
+      #
+      # @raise [PlanMyStuff::ValidationError] when the duplicate target cannot be found
       #
       # @return [PlanMyStuff::Issue]
       #
@@ -1737,7 +1916,7 @@ module PlanMyStuff
       #
       # @return [void]
       #
-      def merge_visibility_allowlist_onto(target)
+      def merge_visibility_allowlist_onto!(target)
         return if metadata.visibility_allowlist.blank?
 
         merged = Array.wrap(target.metadata.visibility_allowlist) | Array.wrap(metadata.visibility_allowlist)
@@ -1748,7 +1927,7 @@ module PlanMyStuff
       #
       # @return [void]
       #
-      def merge_assignees_onto(target)
+      def merge_assignees_onto!(target)
         source_logins = extract_assignee_logins(github_response)
         return if source_logins.empty?
 
@@ -1766,7 +1945,7 @@ module PlanMyStuff
       end
 
       # @return [void]
-      def post_duplicate_back_pointer(target, user:)
+      def post_duplicate_back_pointer!(target, user:)
         visibility = target.metadata.visibility.presence || 'public'
         PlanMyStuff::Comment.create!(
           issue: target,
@@ -1776,11 +1955,11 @@ module PlanMyStuff
         )
       end
 
-      # Closes self as a duplicate of +target+ via GitHub's native
-      # +closeIssue+ GraphQL mutation with +stateReason: DUPLICATE+ and
-      # +duplicateIssueId+. The REST +duplicate_of+ body param is not
-      # recognized; only this GraphQL path actually wires up
-      # +Issue#duplicateOf+ on the closed issue.
+      # Closes self as a duplicate of +target+ via GitHub's native +closeIssue+ GraphQL mutation with
+      # +stateReason: DUPLICATE+ and +duplicateIssueId+. The REST +duplicate_of+ body param is not recognized; only
+      # this GraphQL path actually wires up +Issue#duplicateOf+ on the closed issue.
+      #
+      # @raise [PlanMyStuff::Error] when source or target issue has no node_id
       #
       # @return [void]
       #