plan_my_stuff 0.3.0 → 0.4.0

data/lib/plan_my_stuff/issue.rb

@@ -9,25 +9,30 @@ module PlanMyStuff
   # - `Issue.create!` / `Issue.find` / `Issue.list` return persisted instances
   # - `issue.save!` / `issue.update!` / `issue.reload` for persistence
   class Issue < PlanMyStuff::ApplicationRecord
-    # @return [Integer] GitHub issue number
-    attr_reader :number
-    # @return [String] full body as stored on GitHub
-    attr_reader :raw_body
+    # @return [Integer, nil] GitHub issue number
+    attribute :number, :integer
+    # @return [String, nil] full body as stored on GitHub
+    attribute :raw_body, :string
     # @return [PlanMyStuff::IssueMetadata] parsed metadata (empty when no PMS metadata present)
-    attr_reader :metadata
-
-    # @return [String] issue title
-    attr_accessor :title
-    # @return [String] issue body without the metadata HTML comment
-    attr_writer :body
-    # @return [String] issue state ("open" or "closed")
-    attr_accessor :state
+    attribute :metadata, default: -> { PlanMyStuff::IssueMetadata.new }
+    # @return [String, nil] issue title
+    attribute :title, :string
+    # @return [String, nil] issue state ("open" or "closed")
+    attribute :state, :string
     # @return [Array<String>] label names
-    attr_accessor :labels
+    attribute :labels, default: -> { [] }
     # @return [Time, nil] GitHub's updated_at timestamp
-    attr_reader :updated_at
+    attribute :updated_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)
+    attribute :locked, :boolean, default: false
+    alias locked? locked
     # @return [PlanMyStuff::Repo, nil]
-    attr_reader :repo
+    attribute :repo
+    # @return [String, nil] issue body (user-visible content, separate from metadata)
+    attribute :body, :string
 
     class << self
       # Creates a GitHub issue with PMS metadata embedded in the body.
@@ -39,6 +44,7 @@ module PlanMyStuff
       # @param user [Object, Integer] user object or user_id
       # @param metadata [Hash] custom fields hash
       # @param add_to_project [Boolean, Integer, nil]
+      # @param visibility [String] "public" or "internal"
       # @param visibility_allowlist [Array<Integer>] user IDs for internal comment access
       #
       # @return [PlanMyStuff::Issue]
@@ -51,6 +57,7 @@ module PlanMyStuff
         user: nil,
         metadata: {},
         add_to_project: nil,
+        visibility: 'public',
         visibility_allowlist: []
       )
         raise(ValidationError.new('body must be present', field: :body, expected_type: :string)) if body.blank?
@@ -60,6 +67,7 @@ module PlanMyStuff
 
         issue_metadata = IssueMetadata.build(
           user: user,
+          visibility: visibility,
           custom_fields: metadata,
         )
         issue_metadata.visibility_allowlist = Array.wrap(visibility_allowlist)
@@ -72,6 +80,7 @@ module PlanMyStuff
 
         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)
 
         issue = find(number, repo: resolved_repo)
 
@@ -89,22 +98,43 @@ module PlanMyStuff
           issue_body: true,
         )
 
+        issue.reload
+        PlanMyStuff::Notifications.instrument('issue.created', issue, user: user)
         issue
       end
 
       # Updates an existing GitHub issue.
       #
+      # +metadata:+ accepts either:
+      # - a +PlanMyStuff::IssueMetadata+ instance - treated as the
+      #   full authoritative metadata and serialized as-is (used by
+      #   instance +save!+/+update!+ so local +@metadata+ mutations
+      #   like +metadata.commit_sha = ...+ actually persist).
+      # - a +Hash+ - patch-style merge against the CURRENT remote
+      #   metadata. Top-level keys are merged in; +:custom_fields+
+      #   is merged separately so unrelated fields stay intact.
+      #
       # @param number [Integer]
       # @param repo [Symbol, String, nil] defaults to config.default_repo
       # @param title [String, nil]
       # @param body [String, nil]
-      # @param metadata [Hash, nil] custom fields to merge into existing metadata
+      # @param metadata [PlanMyStuff::IssueMetadata, Hash, nil]
       # @param labels [Array<String>, nil]
       # @param state [Symbol, nil] :open or :closed
+      # @param assignees [Array<String>, String, nil] GitHub logins
       #
       # @return [Object]
       #
-      def update!(number:, repo: nil, title: nil, body: nil, metadata: nil, labels: nil, state: nil, assignees: nil)
+      def update!(
+        number:,
+        repo: nil,
+        title: nil,
+        body: nil,
+        metadata: nil,
+        labels: nil,
+        state: nil,
+        assignees: nil
+      )
         client = PlanMyStuff.client
         resolved_repo = client.resolve_repo(repo)
 
@@ -114,7 +144,11 @@ module PlanMyStuff
         options[:state] = state.to_s unless state.nil?
         options[:assignees] = Array.wrap(assignees) unless assignees.nil?
 
-        if metadata
+        case metadata
+        when PlanMyStuff::IssueMetadata
+          metadata.validate_custom_fields!
+          options[:body] = MetadataParser.serialize(metadata.to_h, '')
+        when Hash
           current = client.rest(:issue, resolved_repo, number)
           current_body = current.respond_to?(:body) ? current.body : current[:body]
           parsed = MetadataParser.parse(current_body)
@@ -133,7 +167,11 @@ module PlanMyStuff
 
         update_body_comment(number, resolved_repo, body) if body
 
-        client.rest(:update_issue, resolved_repo, number, **options) if options.any?
+        return if options.none?
+
+        result = client.rest(:update_issue, resolved_repo, number, **options)
+        store_etag_to_cache(client, resolved_repo, number, result, cache_writer: :write_issue)
+        result
       end
 
       # Finds a single GitHub issue by number and parses its PMS metadata.
@@ -147,7 +185,15 @@ module PlanMyStuff
         client = PlanMyStuff.client
         resolved_repo = client.resolve_repo(repo)
 
-        github_issue = client.rest(:issue, resolved_repo, number)
+        github_issue =
+          fetch_with_etag_cache(
+            client,
+            resolved_repo,
+            number,
+            rest_method: :issue,
+            cache_reader: :read_issue,
+            cache_writer: :write_issue,
+          )
 
         if github_issue.respond_to?(:pull_request) && github_issue.pull_request
           raise(Octokit::NotFound, { method: 'GET', url: "repos/#{resolved_repo}/issues/#{number}" })
@@ -170,43 +216,21 @@ module PlanMyStuff
         client = PlanMyStuff.client
         resolved_repo = client.resolve_repo(repo)
 
-        options = { state: state.to_s, page: page, per_page: per_page }
-        options[:labels] = labels.join(',') if labels.any?
+        params = { state: state.to_s, page: page, per_page: per_page }
+        params[:labels] = labels.sort.join(',') if labels.any?
 
-        github_issues = client.rest(:list_issues, resolved_repo, **options)
-        github_issues.filter_map do |gi|
-          next if gi.respond_to?(:pull_request) && gi.pull_request
+        cached = PlanMyStuff::Cache.read_list(:issue, resolved_repo, params)
+        request_options = cached ? params.merge(headers: { 'If-None-Match' => cached[:etag] }) : params
 
-          build(gi, repo: resolved_repo)
-        end
-      end
+        github_issues = client.rest(:list_issues, resolved_repo, **request_options)
 
-      # Adds user IDs to the visibility allowlist of an issue's metadata.
-      #
-      # @param number [Integer]
-      # @param repo [Symbol, String, nil] defaults to config.default_repo
-      # @param user_ids [Array<Integer>]
-      #
-      # @return [Object] Octokit response
-      #
-      def add_viewers(number:, user_ids:, repo: nil)
-        modify_allowlist(number: number, repo: repo) do |allowlist|
-          allowlist | Array.wrap(user_ids)
+        if cached && not_modified?(client)
+          return cached[:body].map { |gi| build(gi, repo: resolved_repo) }
         end
-      end
 
-      # Removes user IDs from the visibility allowlist of an issue's metadata.
-      #
-      # @param number [Integer]
-      # @param repo [Symbol, String, nil] defaults to config.default_repo
-      # @param user_ids [Array<Integer>]
-      #
-      # @return [Object] Octokit response
-      #
-      def remove_viewers(number:, user_ids:, repo: nil)
-        modify_allowlist(number: number, repo: repo) do |allowlist|
-          allowlist - Array.wrap(user_ids)
-        end
+        filtered = github_issues.reject { |gi| gi.respond_to?(:pull_request) && gi.pull_request }
+        store_list_etag_to_cache(client, :issue, resolved_repo, params, filtered)
+        filtered.map { |gi| build(gi, repo: resolved_repo) }
       end
 
       private
@@ -232,30 +256,6 @@ module PlanMyStuff
             raise(ArgumentError, 'add_to_project: true requires config.default_project_number to be set')
         end
 
-        # Reads an issue's metadata, yields the allowlist for modification,
-        # and PATCHes the issue body with the updated allowlist.
-        #
-        # @param number [Integer]
-        # @param repo [Symbol, String, nil]
-        #
-        # @return [Object] Octokit response
-        #
-        def modify_allowlist(number:, repo:)
-          client = PlanMyStuff.client
-          resolved_repo = client.resolve_repo(repo)
-
-          current = client.rest(:issue, resolved_repo, number)
-          current_body = current.respond_to?(:body) ? current.body : current[:body]
-          parsed = MetadataParser.parse(current_body)
-
-          existing_metadata = parsed[:metadata]
-          allowlist = Array.wrap(existing_metadata[:visibility_allowlist])
-          existing_metadata[:visibility_allowlist] = yield(allowlist)
-
-          new_body = MetadataParser.serialize(existing_metadata, parsed[:body])
-          client.rest(:update_issue, resolved_repo, number, body: new_body)
-        end
-
         # Finds the first PMS comment on an issue and updates its body content,
         # preserving the comment header and metadata.
         #
@@ -275,59 +275,392 @@ module PlanMyStuff
     end
 
     def initialize(**attrs)
-      @number = attrs.delete(:number)
-      @raw_body = nil
-      @metadata = IssueMetadata.new
+      @body_dirty = false
       super
-      @labels ||= []
     end
 
     # @param value [PlanMyStuff::Repo, Symbol, String, nil]
     def repo=(value)
-      @repo = 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.
+    #
+    # @param value [String]
+    #
+    # @return [String]
+    #
+    def body=(value)
+      super
+      @body_dirty = true
+    end
+
+    # @return [Array<PlanMyStuff::Approval>] all required approvers (pending + approved)
+    def approvers
+      metadata.approvals
+    end
+
+    # @return [Array<PlanMyStuff::Approval>] approvers who have not yet approved
+    def pending_approvals
+      approvers.select(&:pending?)
+    end
+
+    # @return [Boolean] true when at least one approver is required on this issue
+    def approvals_required?
+      approvers.any?
+    end
+
+    # @return [Boolean] true when approvers are required AND every approver has approved
+    def fully_approved?
+      approvals_required? && pending_approvals.empty?
+    end
+
+    # 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+.
+    #
+    # @param user_ids [Array<Integer>, Integer]
+    # @param user [Object, nil] actor for the notification event
+    #
+    # @return [Array<Integer>] the new allowlist
+    #
+    def add_viewers(user_ids:, user: nil)
+      ids = Array.wrap(user_ids)
+      modify_allowlist { |allowlist| allowlist | ids }
+      PlanMyStuff::Notifications.instrument('issue.viewers_added', self, user: user, user_ids: ids)
+      metadata.visibility_allowlist
+    end
+
+    # Removes user IDs from this issue's visibility allowlist.
+    #
+    # Fires +plan_my_stuff.issue.viewers_removed+.
+    #
+    # @param user_ids [Array<Integer>, Integer]
+    # @param user [Object, nil] actor for the notification event
+    #
+    # @return [Array<Integer>] the new allowlist
+    #
+    def remove_viewers(user_ids:, user: nil)
+      ids = Array.wrap(user_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.
+    #
+    # 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|
+        existing_ids = current.map(&:user_id)
+        new_ids = ids - existing_ids
+        added = new_ids.map { |id| PlanMyStuff::Approval.new(user_id: id, status: 'pending') }
+        [current + added, added]
+      end
+
+      finish_request_approvals(just_added, user: user, was_fully_approved: was_fully_approved)
+      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?+).
+    #
+    # @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|
+        removed = current.select { |a| ids.include?(a.user_id) }
+        [current - removed, removed]
+      end
+
+      emit_aggregate_events(was_fully_approved: was_fully_approved, trigger: nil, user: user)
+      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+
+    #
+    # @raise [PlanMyStuff::ValidationError] when the caller is not in the approvers list or is already approved
+    #
+    # @return [PlanMyStuff::Approval] the updated approval
+    #
+    def approve!(user:)
+      actor_id = resolve_actor_id!(user)
+
+      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?
+
+        approval.status = 'approved'
+        approval.approved_at = Time.current
+        [current, approval]
+      end
+
+      finish_state_change(:approval_granted, just_approved, user: user, was_fully_approved: was_fully_approved)
+      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+.
+    #
+    # 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+).
+    #
+    # @param user [Object, Integer] the caller
+    # @param target_user_id [Integer, nil] approver whose approval should be revoked; defaults to the caller
+    #
+    # @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
+    #
+    # @return [PlanMyStuff::Approval] the updated approval
+    #
+    def revoke_approval!(user:, target_user_id: nil)
+      actor_id = resolve_actor_id!(user)
+      caller_is_support = PlanMyStuff::UserResolver.support?(PlanMyStuff::UserResolver.resolve(user))
+      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")
+      end
+
+      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?
+
+        approval.status = 'pending'
+        approval.approved_at = nil
+        [current, approval]
+      end
+
+      finish_state_change(
+        :approval_revoked,
+        just_revoked,
+        user: user,
+        was_fully_approved: was_fully_approved,
+        trigger: :revoked,
+      )
+      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.
+    #
+    # @param user [Object, nil] actor for the label notification event
+    #
+    # @return [self]
+    #
+    def enter_waiting_on_user!(user: nil)
+      now = Time.now.utc
+      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)
+
+      self.class.update!(
+        number: number,
+        repo: repo,
+        metadata: {
+          waiting_on_user_at: now.iso8601,
+          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.
+    #
+    # @return [self]
+    #
+    def clear_waiting_on_user!
+      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)
+
+      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,
+        },
+      )
+      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.
+    #
+    # @param comment [PlanMyStuff::Comment] the reopening comment
+    # @param user [Object, nil] actor for the notification event
+    #
+    # @return [self]
+    #
+    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)
+
+      self.class.update!(
+        number: number,
+        repo: repo,
+        state: :open,
+        metadata: { closed_by_inactivity: false },
+      )
+      reload
+
+      PlanMyStuff::Notifications.instrument(
+        'issue.reopened_by_reply',
+        self,
+        user: user,
+        comment: comment,
+      )
+      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.
+    #
+    # 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+
+    #
+    # @return [self]
+    #
+    def archive!(now: Time.now.utc)
+      label = PlanMyStuff.configuration.archived_label
+      return self unless state == 'closed'
+
+      return self if metadata.archived_at.present?
+      return self if labels.include?(label)
+
+      self.class.update!(
+        number: number,
+        repo: repo,
+        metadata: { archived_at: now.utc.iso8601 },
+      )
+
+      PlanMyStuff::Label.ensure!(repo: repo, name: label)
+      PlanMyStuff::Label.add(issue: self, labels: [label])
+
+      remove_from_all_projects!
+
+      PlanMyStuff.client.rest(:lock_issue, repo.full_name, number)
+
+      reload
+
+      PlanMyStuff::Notifications.instrument(
+        'issue.archived',
+        self,
+        reason: :aged_closed,
+      )
+      self
     end
 
-    # Persists the issue. Creates if new, updates if persisted.
+    # 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
     #
     # @return [self]
     #
-    def save!
+    def save!(user: nil, skip_notification: false)
       if new_record?
         created = self.class.create!(
           title: title,
           body: body,
           repo: repo,
           labels: labels || [],
+          user: user || metadata.created_by,
+          metadata: metadata.custom_fields.to_h,
+          visibility: metadata.visibility,
+          visibility_allowlist: Array.wrap(metadata.visibility_allowlist),
         )
         hydrate_from_issue(created)
       else
-        update!(body: body, state: state, labels: labels)
+        captured_changes = changes.dup
+        persist_update!
+        instrument_update(captured_changes, user) unless skip_notification
       end
 
       self
     end
 
-    # Updates this issue on GitHub. Raises StaleObjectError if the remote
-    # has been modified since this instance was loaded.
+    # 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 attrs [Hash] attributes to update (title:, body:, state:, labels:, metadata:)
+    # @param user [Object, nil] actor for notification events
     #
     # @raise [PlanMyStuff::StaleObjectError] if remote updated_at differs from local
     #
     # @return [self]
     #
-    def update!(**attrs)
-      raise_if_stale!
-
-      self.class.update!(
-        number: number,
-        repo: repo,
-        **attrs,
-      )
-
-      reload
+    def update!(user: nil, skip_notification: false, **attrs)
+      apply_update_attrs!(attrs)
+      save!(user: user, skip_notification: skip_notification)
     end
 
     # Re-fetches this issue from GitHub and updates all local attributes.
@@ -348,6 +681,14 @@ module PlanMyStuff
       @comments ||= load_comments
     end
 
+    # GitHub web URL for this issue, for escape-hatch "View on GitHub" links.
+    #
+    # @return [String, nil]
+    #
+    def html_url
+      safe_read_field(github_response, :html_url)
+    end
+
     # @return [Boolean]
     def pms_issue?
       metadata.schema_version.present?
@@ -373,14 +714,14 @@ module PlanMyStuff
     # @return [String, nil]
     #
     def body
-      return @body if new_record?
-
-      return @body unless pms_issue?
+      return super if new_record?
+      return super if @body_dirty
+      return super unless pms_issue?
 
       bc = body_comment
       return bc.body_without_header if bc.present?
 
-      @body
+      super
     end
 
     # Delegates visibility check to metadata.
@@ -398,93 +739,1053 @@ module PlanMyStuff
       end
     end
 
-    private
+    # 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>]
+    #
+    def related
+      links_cache[:related] ||= fetch_related
+    end
 
-      # Populates this instance from a GitHub API response.
-      #
-      # @param github_issue [Object] Octokit issue response
-      # @param repo [String] resolved repo path
-      #
-      # @return [void]
-      #
-      def hydrate_from_github(github_issue, repo:)
-        @number = read_field(github_issue, :number)
-        @title = read_field(github_issue, :title)
-        @state = read_field(github_issue, :state)
-        @raw_body = read_field(github_issue, :body) || ''
-        @updated_at = parse_github_time(safe_read_field(github_issue, :updated_at))
-        @labels = extract_labels(github_issue)
-        self.repo = repo
+    # 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
+    # @param reciprocal [Boolean] internal flag; set by the mirror call
+    #
+    # @return [PlanMyStuff::Link]
+    #
+    def add_related!(target, user: nil, reciprocal: false)
+      link = build_link(target, type: :related)
+      validate_not_self!(link)
 
-        parsed = MetadataParser.parse(@raw_body)
-        @metadata = IssueMetadata.from_hash(parsed[:metadata])
-        @body = parsed[:body]
-        @persisted = true
-        @comments = nil
-      end
+      existing = current_links
+      return link if existing.include?(link)
 
-      # Copies attributes from another Issue instance into self.
-      #
-      # @param other [PlanMyStuff::Issue]
-      #
-      # @return [void]
-      #
-      def hydrate_from_issue(other)
-        @number = other.number
-        @title = other.title
-        @state = other.state
-        @body = other.instance_variable_get(:@body)
-        @raw_body = other.raw_body
-        @updated_at = other.updated_at
-        @labels = other.labels
-        @repo = other.repo
-        @metadata = other.metadata
-        @persisted = true
-        @comments = nil
+      persist_links!(existing + [link])
+      unless reciprocal
+        mirror_on_target(link, user: user) { |other| other.add_related!(self, user: user, reciprocal: true) }
       end
 
-      # Raises StaleObjectError if the remote issue has been modified
-      # since this instance was loaded.
-      #
-      # @raise [PlanMyStuff::StaleObjectError]
-      #
-      # @return [void]
-      #
-      def raise_if_stale!
-        return if new_record?
-        return if updated_at.nil?
+      link
+    end
 
-        remote = self.class.find(number, repo: repo)
-        remote_time = remote.updated_at
-        local_time = updated_at
+    # 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]
+    # @param reciprocal [Boolean]
+    #
+    # @return [PlanMyStuff::Link]
+    #
+    def remove_related!(target, user: nil, reciprocal: false)
+      link = build_link(target, type: :related)
+      validate_not_self!(link)
 
-        return if remote_time.nil?
-        return if local_time && remote_time.to_i == local_time.to_i
+      existing = current_links
+      return link if existing.exclude?(link)
 
-        raise(StaleObjectError.new(
-          "Issue ##{number} has been modified remotely",
-          local_updated_at: local_time,
-          remote_updated_at: remote_time,
-        ))
+      persist_links!(existing.reject { |l| l == link })
+      unless reciprocal
+        mirror_on_target(link, user: user) { |other| other.remove_related!(self, user: user, reciprocal: true) }
       end
 
-      # @return [Array<String>]
-      def extract_labels(github_issue)
-        raw = read_field(github_issue, :labels) || []
-        raw.map { |label| label_name(label) }
-      end
+      link
+    end
 
-      # @return [String]
-      def label_name(label)
-        return label.name if label.respond_to?(:name)
-        return label[:name] || label['name'] if label.is_a?(Hash)
+    # Lazy-memoized parent issue via GitHub's native sub-issues API.
+    # GitHub enforces at most one parent per issue.
+    #
+    # @return [PlanMyStuff::Issue, nil]
+    #
+    def parent
+      return links_cache[:parent] if links_cache.key?(:parent)
 
-        label.to_s
-      end
+      links_cache[:parent] = fetch_parent
+    end
 
-      # @return [Array<PlanMyStuff::Comment>]
-      def load_comments
-        Comment.list(issue: self)
+    # Lazy-memoized sub-issues via GitHub's native sub-issues API.
+    #
+    # @return [Array<PlanMyStuff::Issue>]
+    #
+    def sub_tickets
+      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;
+    # notifications are handled by GitHub itself.
+    #
+    # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
+    #
+    # @return [PlanMyStuff::Link]
+    #
+    def add_sub_issue!(target)
+      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).
+    #
+    # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
+    #
+    # @return [PlanMyStuff::Link]
+    #
+    def remove_sub_issue!(target)
+      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.
+    #
+    # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
+    #
+    # @return [PlanMyStuff::Link]
+    #
+    def set_parent!(target)
+      parent.presence&.remove_sub_issue!(self)
+
+      target_issue = resolve_target_issue(target, type: :parent)
+      target_issue.add_sub_issue!(self)
+      invalidate_links_cache!
+
+      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.
+    #
+    # @return [PlanMyStuff::Link, nil]
+    #
+    def remove_parent!
+      current = parent
+      return if current.nil?
+
+      current.remove_sub_issue!(self)
+      invalidate_links_cache!
+
+      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.
+    #
+    # @return [Array<PlanMyStuff::Issue>]
+    #
+    def blocked_by
+      links_cache[:blocked_by] ||= fetch_dependencies('blocked_by')
+    end
+
+    # Lazy-memoized issues that self blocks.
+    #
+    # @return [Array<PlanMyStuff::Issue>]
+    #
+    def blocking
+      links_cache[:blocking] ||= fetch_dependencies('blocking')
+    end
+
+    # 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)
+      validate_not_self!(link)
+
+      target_issue = resolve_target_issue(target, type: :blocked_by)
+      PlanMyStuff.client.rest(
+        :post,
+        dependency_path('blocked_by'),
+        { issue_id: target_issue.__send__(:require_github_id!) },
+      )
+      invalidate_links_cache!
+      link
+    end
+
+    # Removes the record that +target+ blocks self.
+    #
+    # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
+    #
+    # @return [PlanMyStuff::Link]
+    #
+    def remove_blocker!(target)
+      link = build_link(target, type: :blocked_by)
+      validate_not_self!(link)
+
+      target_issue = resolve_target_issue(target, type: :blocked_by)
+      PlanMyStuff.client.rest(
+        :delete,
+        "#{dependency_path('blocked_by')}/#{target_issue.__send__(:require_github_id!)}",
+      )
+      invalidate_links_cache!
+      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.
+    #
+    # @return [PlanMyStuff::Issue, nil]
+    #
+    def duplicate_of
+      return links_cache[:duplicate_of] if links_cache.key?(:duplicate_of)
+
+      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.
+    #
+    # Side effects, in order:
+    # 1. Resolves +target+; raises +ValidationError+ if missing.
+    # 2. Raises +ValidationError+ when self is already closed.
+    # 3. Merges self's +visibility_allowlist+ onto target.
+    # 4. Merges self's assignees onto target.
+    # 5. Posts a PMS comment on target with the back-pointer.
+    # 6. Closes self with +state_reason: :duplicate+ and
+    #    +duplicate_of: { owner:, repo:, number: }+.
+    # 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.
+    #
+    # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
+    # @param user [Object, nil] actor for notification + comment
+    #
+    # @return [PlanMyStuff::Link]
+    #
+    def mark_duplicate!(target, user: nil)
+      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)
+      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)
+    end
+
+    # GitHub GraphQL node ID (required for native sub-issue mutations).
+    # Read from the hydrated REST response.
+    #
+    # @return [String, nil]
+    #
+    def github_node_id
+      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).
+    #
+    # @return [Integer, nil]
+    #
+    def github_id
+      safe_read_field(github_response, :id)
+    end
+
+    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.
+      #
+      # @yieldparam allowlist [Array<Integer>]
+      # @yieldreturn [Array<Integer>] the new allowlist
+      #
+      # @return [void]
+      #
+      def modify_allowlist
+        new_allowlist = yield(Array.wrap(metadata.visibility_allowlist))
+        self.class.update!(
+          number: number,
+          repo: repo,
+          metadata: { visibility_allowlist: new_allowlist },
+        )
+        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]+.
+      #
+      # @yieldparam current [Array<PlanMyStuff::Approval>] deep-copied approvals
+      # @yieldreturn [Array(Array<PlanMyStuff::Approval>, Object)] +[new_list, extra]+
+      #
+      # @return [Array(Object, Boolean)]
+      #
+      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) }
+
+        new_list, extra = yield(current)
+
+        new_pending_count = new_list.count(&:pending?)
+        metadata_updates = { approvals: new_list.map(&:to_h) }
+        metadata_updates.merge!(waiting_on_approval_metadata_updates(was_pending_count, new_pending_count))
+
+        self.class.update!(number: number, repo: repo, metadata: metadata_updates)
+        reload
+
+        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.
+      #
+      # @param was [Integer] pending count before the mutation
+      # @param now [Integer] pending count after the mutation
+      #
+      # @return [Hash]
+      #
+      def waiting_on_approval_metadata_updates(was, now)
+        if now > was
+          ts = Time.now.utc
+          {
+            waiting_on_approval_at: ts.iso8601,
+            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,
+          }
+        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.
+      #
+      # @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)
+        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)
+        elsif now.zero? && was.positive?
+          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.
+      #
+      # @param user [Object, Integer, nil]
+      #
+      # @return [void]
+      #
+      def guard_support!(user)
+        resolved = PlanMyStuff::UserResolver.resolve(user)
+        return if resolved && PlanMyStuff::UserResolver.support?(resolved)
+
+        raise(PlanMyStuff::AuthorizationError, 'Only support users may manage approvers')
+      end
+
+      # Resolves +user+ to an integer user_id. Raises +ArgumentError+
+      # when +user+ is +nil+.
+      #
+      # @param user [Object, Integer]
+      #
+      # @return [Integer]
+      #
+      def resolve_actor_id!(user)
+        raise(ArgumentError, 'user: is required') if user.nil?
+
+        resolved = PlanMyStuff::UserResolver.resolve(user)
+        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.
+      #
+      # @param added [Array<PlanMyStuff::Approval>]
+      # @param user [Object, nil]
+      # @param was_fully_approved [Boolean]
+      #
+      # @return [void]
+      #
+      def finish_request_approvals(added, user:, was_fully_approved:)
+        return if added.empty?
+
+        PlanMyStuff::Notifications.instrument(
+          'issue.approval_requested',
+          self,
+          user: user,
+          approvals: added,
+        )
+        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.
+      #
+      # @param event [Symbol] +:approval_granted+ or +:approval_revoked+
+      # @param approval [PlanMyStuff::Approval]
+      # @param user [Object, nil]
+      # @param was_fully_approved [Boolean]
+      # @param trigger [Symbol, nil] passed through to +approvals_invalidated+
+      #
+      # @return [void]
+      #
+      def finish_state_change(event, approval, user:, was_fully_approved:, trigger: nil)
+        PlanMyStuff::Notifications.instrument(
+          "issue.#{event}",
+          self,
+          user: user,
+          approval: approval,
+        )
+        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).
+      #
+      # @param was_fully_approved [Boolean]
+      # @param trigger [Symbol, nil]
+      # @param user [Object, nil]
+      #
+      # @return [void]
+      #
+      def emit_aggregate_events(was_fully_approved:, trigger:, user:)
+        now = fully_approved?
+
+        if !was_fully_approved && now
+          PlanMyStuff::Notifications.instrument('issue.all_approved', self, user: user)
+        elsif was_fully_approved && !now && approvals_required?
+          PlanMyStuff::Notifications.instrument(
+            'issue.approvals_invalidated',
+            self,
+            user: user,
+            trigger: trigger,
+          )
+        end
+      end
+
+      # Populates this instance from a GitHub API response.
+      #
+      # @param github_issue [Object] Octokit issue response
+      # @param repo [String] resolved repo path
+      #
+      # @return [void]
+      #
+      def hydrate_from_github(github_issue, repo:)
+        @github_response = github_issue
+        self.number = read_field(github_issue, :number)
+        self.title = read_field(github_issue, :title)
+        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.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.repo = repo
+
+        parsed = MetadataParser.parse(raw_body)
+        self.metadata = IssueMetadata.from_hash(parsed[:metadata])
+        self.body = parsed[:body]
+        @body_dirty = false
+        persisted!
+        @comments = nil
+        invalidate_links_cache!
+      end
+
+      # Copies attributes from another Issue instance into self.
+      #
+      # @param other [PlanMyStuff::Issue]
+      #
+      # @return [void]
+      #
+      def hydrate_from_issue(other)
+        @github_response = other.github_response
+        self.number = other.number
+        self.title = other.title
+        self.state = other.state
+        self.body = other.attributes['body']
+        @body_dirty = false
+        self.raw_body = other.raw_body
+        self.updated_at = other.updated_at
+        self.closed_at = other.closed_at
+        self.locked = other.locked
+        self.labels = other.labels
+        self.repo = other.repo
+        self.metadata = other.metadata
+        persisted!
+        @comments = nil
+        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.
+      #
+      # @param from [Time] baseline timestamp
+      #
+      # @return [String, nil]
+      #
+      def format_next_reminder_at(from:)
+        days = metadata.reminder_days.presence || PlanMyStuff.configuration.reminder_days
+        return if days.empty?
+
+        (from + days.first.days).utc.iso8601
+      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.
+      #
+      # @param captured [Hash] +ActiveModel::Dirty+ changes captured before +persist_update!+
+      # @param user [Object, nil]
+      #
+      # @return [void]
+      #
+      def instrument_update(captured, user)
+        case captured['state']
+        when %w[open closed]
+          PlanMyStuff::Notifications.instrument('issue.closed', self, user: user)
+        when %w[closed open]
+          PlanMyStuff::Notifications.instrument('issue.reopened', self, user: user)
+        else
+          PlanMyStuff::Notifications.instrument('issue.updated', self, user: user, changes: captured)
+        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.
+      #
+      # @param attrs [Hash] the kwargs hash being assembled for
+      #   +Issue.update!+; mutated in place
+      #
+      # @return [void]
+      #
+      def clear_waiting_state_on_close!(attrs)
+        return unless state_changed?
+        return unless state_was == 'open'
+        return unless state == 'closed'
+
+        return if metadata.waiting_on_user_at.blank? && metadata.waiting_on_approval_at.blank?
+
+        waiting_labels = [
+          PlanMyStuff.configuration.waiting_on_user_label,
+          PlanMyStuff.configuration.waiting_on_approval_label,
+        ]
+        attrs[:labels] = Array.wrap(attrs[:labels]) - waiting_labels
+
+        metadata.waiting_on_user_at = nil
+        metadata.waiting_on_approval_at = nil
+        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.
+      #
+      # @param attrs [Hash] the kwargs hash being assembled for
+      #   +Issue.update!+; mutated in place
+      #
+      # @return [void]
+      #
+      def clear_inactivity_state_on_reopen!(attrs)
+        return unless state_changed?
+        return unless state_was == 'closed'
+        return unless state == 'open'
+        return unless metadata.closed_by_inactivity
+
+        attrs[:labels] = Array.wrap(attrs[:labels]) - [PlanMyStuff.configuration.user_inactive_label]
+        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]
+      #
+      # @return [void]
+      #
+      def persist_update!
+        raise_if_stale!
+
+        attrs = {
+          number: number,
+          repo: repo,
+          title: title,
+          state: state,
+          labels: labels || [],
+          metadata: metadata,
+        }
+        attrs[:body] = body if @body_dirty
+        attrs[:assignees] = @pending_assignees unless @pending_assignees.nil?
+
+        clear_waiting_state_on_close!(attrs)
+        clear_inactivity_state_on_reopen!(attrs)
+
+        self.class.update!(**attrs)
+
+        @body_dirty = false
+        @pending_assignees = nil
+        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).
+      #
+      # @return [void]
+      #
+      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)
+        @pending_assignees = attrs[:assignees] if attrs.key?(:assignees)
+        apply_metadata_attrs!(attrs[:metadata]) if attrs.key?(:metadata)
+      end
+
+      # @return [void]
+      def apply_metadata_attrs!(md_hash)
+        return if md_hash.nil?
+
+        md_hash.each do |key, value|
+          if key == :custom_fields
+            value.each { |k, v| metadata.custom_fields[k] = v }
+          elsif metadata.respond_to?("#{key}=")
+            metadata.public_send("#{key}=", value)
+          end
+        end
+      end
+
+      # Raises StaleObjectError if the remote issue has been modified
+      # since this instance was loaded.
+      #
+      # @raise [PlanMyStuff::StaleObjectError]
+      #
+      # @return [void]
+      #
+      def raise_if_stale!
+        return if new_record?
+        return if updated_at.nil?
+
+        remote = self.class.find(number, repo: repo)
+        remote_time = remote.updated_at
+        local_time = updated_at
+
+        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,
+        ))
+      end
+
+      # @return [Array<String>]
+      def extract_labels(github_issue)
+        raw = read_field(github_issue, :labels) || []
+        raw.map { |label| label_name(label) }
+      end
+
+      # @return [String]
+      def label_name(label)
+        return label.name if label.respond_to?(:name)
+        return label[:name] || label['name'] if label.is_a?(Hash)
+
+        label.to_s
+      end
+
+      # @return [Array<PlanMyStuff::Comment>]
+      def load_comments
+        Comment.list(issue: self)
+      end
+
+      # @return [Hash{Symbol => Array}]
+      def links_cache
+        @links_cache ||= {}
+      end
+
+      # Clears all memoized link readers. Called from +#hydrate_from_github+
+      # and after any successful write.
+      #
+      # @return [void]
+      #
+      def invalidate_links_cache!
+        @links_cache = {}
+      end
+
+      # 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)
+      end
+
+      # @raise [PlanMyStuff::ValidationError]
+      # @return [void]
+      #
+      def validate_not_self!(link)
+        return if link.issue_number != number
+        return unless link.same_repo?(repo)
+
+        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.
+      #
+      # @return [Array<PlanMyStuff::Link>]
+      #
+      def current_links
+        metadata.links.filter_map do |entry|
+          next entry if entry.is_a?(PlanMyStuff::Link)
+
+          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
+      # in-memory reads see the change without a +reload+.
+      #
+      # @param new_links [Array<PlanMyStuff::Link>]
+      #
+      # @return [void]
+      #
+      def persist_links!(new_links)
+        self.class.update!(
+          number: number,
+          repo: repo,
+          metadata: { links: new_links.map(&:to_h) },
+        )
+        metadata.links = new_links
+        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.
+      #
+      # @return [void]
+      #
+      def remove_from_all_projects!
+        client = PlanMyStuff.client
+        owner = repo.organization
+        repo_name = repo.name
+        cursor = nil
+
+        10.times do
+          data = client.graphql(
+            PlanMyStuff::GraphQL::Queries::LIST_ISSUE_PROJECT_ITEMS,
+            variables: { owner: owner, repo: repo_name, number: number, cursor: cursor },
+          )
+
+          connection = data.dig(:repository, :issue, :projectItems) || {}
+          nodes = Array.wrap(connection[:nodes])
+
+          nodes.each do |node|
+            PlanMyStuff::ProjectItem.delete_item(
+              item_id: node[:id],
+              project_number: node.dig(:project, :number),
+            )
+          end
+
+          page_info = connection[:pageInfo] || {}
+          break unless page_info[:hasNextPage]
+
+          cursor = page_info[:endCursor]
+        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.
+      #
+      # @param link [PlanMyStuff::Link]
+      # @param user [Object, nil]
+      #
+      # @return [void]
+      #
+      def mirror_on_target(link, user:)
+        target = PlanMyStuff::Issue.find(link.issue_number, repo: link.repo)
+        yield(target)
+      rescue PlanMyStuff::Error, Octokit::Error => e
+        PlanMyStuff::Notifications.instrument(
+          'issue.link_reciprocal_failed',
+          self,
+          user: user,
+          link: link,
+          error: e.message,
+        )
+      end
+
+      # @return [Array<PlanMyStuff::Issue>]
+      def fetch_related
+        current_links.filter_map do |link|
+          next unless link.type == 'related'
+
+          PlanMyStuff::Issue.find(link.issue_number, repo: link.repo)
+        rescue PlanMyStuff::APIError, Octokit::NotFound
+          next
+        end
+      end
+
+      # @return [PlanMyStuff::Issue, nil]
+      def fetch_parent
+        response = PlanMyStuff.client.rest(:get, parent_path)
+        return if response.blank?
+
+        parent_number = response.respond_to?(:number) ? response.number : response[:number]
+        PlanMyStuff::Issue.find(parent_number, repo: repo)
+      rescue PlanMyStuff::APIError => e
+        return if e.status == 404
+
+        raise
+      end
+
+      # @return [Array<PlanMyStuff::Issue>]
+      def fetch_sub_tickets
+        response = PlanMyStuff.client.rest(:get, sub_issues_path)
+        Array.wrap(response).filter_map do |row|
+          sub_number = row.respond_to?(:number) ? row.number : row[:number]
+          PlanMyStuff::Issue.find(sub_number, repo: repo)
+        rescue PlanMyStuff::APIError, Octokit::NotFound
+          next
+        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.
+      #
+      # @return [PlanMyStuff::Issue]
+      #
+      def resolve_target_issue(target, type:)
+        return target if target.is_a?(PlanMyStuff::Issue)
+
+        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.
+      #
+      # @return [PlanMyStuff::Link]
+      #
+      def mutate_sub_issue!(target, method:, path:)
+        link = build_link(target, type: :sub_ticket)
+        validate_not_self!(link)
+
+        target_issue = resolve_target_issue(target, type: :sub_ticket)
+        PlanMyStuff.client.rest(
+          method,
+          path,
+          { sub_issue_id: target_issue.__send__(:require_github_id!) },
+        )
+        invalidate_links_cache!
+        link
+      end
+
+      # @return [String]
+      def parent_path
+        "/repos/#{repo.organization}/#{repo.name}/issues/#{number}/parent"
+      end
+
+      # @return [String]
+      def sub_issues_path
+        "/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).
+      #
+      # @return [String]
+      #
+      def remove_sub_issue_path
+        "/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).
+      #
+      # @param side [String] "blocked_by" or "blocking"
+      #
+      # @return [Array<PlanMyStuff::Issue>]
+      #
+      def fetch_dependencies(side)
+        response = PlanMyStuff.client.rest(:get, dependency_path(side))
+        Array.wrap(response).filter_map do |row|
+          number = row.respond_to?(:number) ? row.number : row[:number]
+          PlanMyStuff::Issue.find(number, repo: repo)
+        rescue PlanMyStuff::APIError, Octokit::NotFound
+          next
+        end
+      end
+
+      # @return [String]
+      def dependency_path(side)
+        "/repos/#{repo.organization}/#{repo.name}/issues/#{number}/dependencies/#{side}"
+      end
+
+      # @raise [PlanMyStuff::Error]
+      # @return [Integer]
+      #
+      def require_github_id!
+        id = github_id
+        raise(PlanMyStuff::Error, "Issue ##{number} has no database id; cannot run native REST mutation") if id.nil?
+
+        id
+      end
+
+      # @return [PlanMyStuff::Issue, nil]
+      def fetch_duplicate_of
+        data = PlanMyStuff.client.graphql(
+          PlanMyStuff::GraphQL::Queries::FETCH_DUPLICATE_OF,
+          variables: { owner: repo.organization, repo: repo.name, number: number },
+        )
+        issue_data = data.dig(:repository, :issue) || {}
+        return unless issue_data[:stateReason].to_s.casecmp?('DUPLICATE')
+
+        the_dupe = issue_data[:duplicateOf]
+        return if the_dupe.blank?
+
+        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.
+      #
+      # @return [PlanMyStuff::Issue]
+      #
+      def resolve_duplicate_target!(target)
+        resolve_target_issue(target, type: :duplicate_of)
+      rescue Octokit::NotFound, PlanMyStuff::APIError => e
+        raise(PlanMyStuff::ValidationError, "Duplicate target not found: #{e.message}")
+      end
+
+      # Unions self's visibility_allowlist onto +target+'s.
+      #
+      # @return [void]
+      #
+      def merge_visibility_allowlist_onto(target)
+        return if metadata.visibility_allowlist.blank?
+
+        merged = Array.wrap(target.metadata.visibility_allowlist) | Array.wrap(metadata.visibility_allowlist)
+        target.update!(metadata: { visibility_allowlist: merged })
+      end
+
+      # Unions self's GitHub assignees (by login) onto +target+'s.
+      #
+      # @return [void]
+      #
+      def merge_assignees_onto(target)
+        source_logins = extract_assignee_logins(github_response)
+        return if source_logins.empty?
+
+        merged = extract_assignee_logins(target.github_response) | source_logins
+        target.update!(assignees: merged)
+      end
+
+      # @param response [Object] Octokit issue response
+      #
+      # @return [Array<String>]
+      #
+      def extract_assignee_logins(response)
+        raw = safe_read_field(response, :assignees) || []
+        raw.filter_map { |a| a.respond_to?(:login) ? a.login : a[:login] || a['login'] }
+      end
+
+      # @return [void]
+      def post_duplicate_back_pointer(target, user:)
+        visibility = target.metadata.visibility.presence || 'public'
+        PlanMyStuff::Comment.create!(
+          issue: target,
+          body: "Marked duplicate of this by #{repo.full_name}##{number}",
+          user: user,
+          visibility: visibility.to_sym,
+        )
+      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.
+      #
+      # @return [void]
+      #
+      def close_as_duplicate!(target)
+        source_node_id = github_node_id
+        target_node_id = target.github_node_id
+        raise(PlanMyStuff::Error, "Issue ##{number} has no node_id") if source_node_id.blank?
+        raise(PlanMyStuff::Error, "Target issue ##{target.number} has no node_id") if target_node_id.blank?
+
+        PlanMyStuff.client.graphql(
+          PlanMyStuff::GraphQL::Queries::CLOSE_AS_DUPLICATE,
+          variables: { issueId: source_node_id, duplicateIssueId: target_node_id },
+        )
       end
   end
 end