plan_my_stuff 0.1.0 → 1.0.0

data/lib/plan_my_stuff/issue.rb

@@ -9,27 +9,80 @@ 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
+    # Value object returned by +Issue.list_page_info+: the fetched issues plus pagination metadata read from the
+    # +Link+ header of the +list_issues+ response. +:total_pages+ is intentionally absent -- GitHub's issues endpoint
+    # is cursor-paginated and never advertises +rel="last"+.
+    #
+    # @!attribute [r] issues
+    #   @return [Array<PlanMyStuff::Issue>]
+    # @!attribute [r] page
+    #   @return [Integer] echo of the requested page
+    # @!attribute [r] per_page
+    #   @return [Integer] echo of the requested per_page
+    PageInfo = Data.define(:issues, :page, :per_page, :has_next, :has_prev) do
+      alias_method :has_next?, :has_next
+      alias_method :has_prev?, :has_prev
+    end
+
+    include PlanMyStuff::IssueExtractions::Approvals
+    include PlanMyStuff::IssueExtractions::Links
+    include PlanMyStuff::IssueExtractions::Viewers
+    include PlanMyStuff::IssueExtractions::Waiting
+
+    # @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
-    # @return [String] resolved repo path (e.g. "Org/Repo")
-    attr_accessor :repo
+    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)
+    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
@@ -37,7 +90,18 @@ 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
+      # @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.
+      # @param issue_fields [Hash{String,Symbol => Object,nil}, nil] GitHub Issue Field values to apply after the
+      #   issue is created. Delegates to +#set_issue_fields!+, so the same coercion rules and
+      #   +IssueFieldsNotEnabledError+ behavior apply. +nil+ or an empty hash is a no-op.
+      # @param attachments [Array] files to upload to +config.attachment_repo+ and record on the body comment. Each
+      #   entry may be an uploaded-file object responding to +#path+ and +#original_filename+ (e.g. Rails
+      #   +ActionDispatch::Http::UploadedFile+), a String/Pathname path to a local file, or a pre-built
+      #   +PlanMyStuff::Attachment+ instance (passthrough, no re-upload). Forwarded to the body comment's
+      #   +attachments:+ kwarg; see +Comment.create!+ for full detail.
       #
       # @return [PlanMyStuff::Issue]
       #
@@ -49,100 +113,201 @@ module PlanMyStuff
         user: nil,
         metadata: {},
         add_to_project: nil,
-        visibility_allowlist: []
+        visibility: 'public',
+        visibility_allowlist: [],
+        issue_type: nil,
+        issue_fields: nil,
+        attachments: []
       )
-        raise(ValidationError.new('body must be present', field: :body, expected_type: :string)) if body.blank?
+        if issue_fields.present? && !PlanMyStuff.configuration.issue_fields_enabled
+          raise(PlanMyStuff::IssueFieldsNotEnabledError)
+        end
+
+        if issue_fields.present?
+          issue_fields = issue_fields.to_h.transform_keys(&:to_s)
+          issue_fields['Issue Status'] = 'Submitted' if issue_fields['Issue Status'].blank?
+        end
+
+        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,
         )
         issue_metadata.visibility_allowlist = Array.wrap(visibility_allowlist)
+        issue_metadata.validate_custom_fields!
+
+        serialized_body = PlanMyStuff::MetadataParser.serialize!(issue_metadata.to_h, '')
 
-        serialized_body = 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 = build(result, repo: resolved_repo)
+        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,
           visibility: issue_metadata.visibility.to_sym,
           skip_responded: true,
           issue_body: true,
+          attachments: attachments,
         )
 
+        issue.set_issue_fields!(issue_fields) if issue_fields.present?
+
+        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
+      # @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.)
+      # @param issue_fields [Hash{String,Symbol => Object,nil}, nil] GitHub Issue Field values to apply after the
+      #   PATCH (or instead of it, when no other attrs are provided). Delegates to +#set_issue_fields!+, so the same
+      #   coercion rules and +IssueFieldsNotEnabledError+ behavior apply. +nil+ or an empty hash is a no-op.
       #
       # @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,
+        issue_type: ISSUE_TYPE_UNCHANGED,
+        issue_fields: nil
+      )
         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?
-
-        if metadata
+        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] =
+            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] || {})
           existing_metadata = existing_metadata.merge(metadata)
           existing_metadata[:custom_fields] = merged_custom_fields
+          PlanMyStuff::CustomFields.new(
+            PlanMyStuff.configuration.custom_fields_for(:issue),
+            merged_custom_fields,
+          ).validate!
 
-          existing_metadata[:updated_at] = Time.now.utc.iso8601
-          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
+
+        updated_issue = find(number, repo: resolved_repo).set_issue_fields!(issue_fields) if issue_fields.present?
+        return updated_issue if options.none?
 
-        client.rest(:update_issue, resolved_repo, number, **options) if options.any?
+        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.
       #
-      # @param number [Integer]
-      # @param repo [Symbol, String, nil] defaults to config.default_repo
+      # Accepts a numeric id (Integer or all-digit String) plus an optional +repo:+ kwarg, or a nickname-id String
+      # (e.g. +"Rawr-1234"+) where the repo is encoded in the prefix and +repo:+ is ignored.
+      #
+      # @raise [Octokit::NotFound] when the issue number resolves to a pull request
+      # @raise [ArgumentError] when a nickname-id String references an unknown repo nickname
+      #
+      # @param id_or_number [Integer, String]
+      # @param repo [Symbol, String, nil] defaults to config.default_repo; ignored when +id_or_number+ is a nickname id
       #
       # @return [PlanMyStuff::Issue]
       #
-      def find(number, repo: nil)
+      def find(id_or_number, repo: nil)
+        number, resolved_repo = resolve_find_args(id_or_number, repo)
         client = PlanMyStuff.client
-        resolved_repo = client.resolve_repo(repo)
-
-        github_issue = client.rest(:issue, resolved_repo, number)
 
-        if github_issue.respond_to?(:pull_request) && github_issue.pull_request
+        github_issue =
+          fetch_with_etag_cache(
+            client,
+            resolved_repo,
+            number,
+            rest_method: :issue,
+            cache_reader: :read_issue,
+            cache_writer: :write_issue,
+          )
+
+        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
 
@@ -151,59 +316,452 @@ module PlanMyStuff
 
       # Lists GitHub issues with optional filters and pagination.
       #
+      # +issue_fields:+ is a Hash keyed by GitHub Issue Field display name (String / Symbol). Each value is either
+      # a scalar (equality match -- Date / Time are emitted as ISO 8601, everything else as +to_s+) or a +Range+ for
+      # numeric / date bounds:
+      #
+      # - +Date.parse('2026-01-01')..Date.today+ -> +start-date:>=2026-01-01,start-date:<=2026-05-21+
+      # - +Date.parse('2026-01-01')...Date.today+ -> +start-date:>=2026-01-01,start-date:<2026-05-21+ (exclusive end)
+      # - +..Date.today+ (beginless) / +Date.parse('2026-01-01')..+ (endless) drop the unbounded side
+      #
+      # Multiple field constraints AND together. Composes with the existing +priority_list:+ filter: both feed the
+      # same +issue_field_values+ query param.
+      #
+      # @raise [ArgumentError] when +priority_list: false+ is passed, or when +issue_type:+ is an Array (GitHub's
+      #   REST +type+ param only accepts a single value)
+      # @raise [PlanMyStuff::IssueFieldsNotEnabledError] when +issue_fields:+ is passed and
+      #   +config.issue_fields_enabled+ is +false+
+      #
       # @param repo [Symbol, String, nil] defaults to config.default_repo
       # @param state [Symbol] :open, :closed, or :all
       # @param labels [Array<String>]
+      # @param issue_type [String, Symbol, nil] a single GitHub issue type name. Symbols resolve through
+      #   +ISSUE_TYPE_NICKNAMES+ then +config.issue_types+ for org-specific renames.
+      # @param issue_fields [Hash{String,Symbol => Object,Range,nil}, nil] GitHub Issue Field equality / range
+      #   filters. See description for the value shapes the gem accepts.
+      # @param priority_list [Boolean, nil] when +true+, restricts to issues whose +Priority List+ issue field is
+      #   +Yes+ (server-side filter via the +issue_field_values+ query param). +false+ raises +ArgumentError+ -- GitHub
+      #   has no negation qualifier. Silently dropped when +config.issue_fields_enabled+ is +false+.
       # @param page [Integer]
       # @param per_page [Integer]
       #
       # @return [Array<PlanMyStuff::Issue>]
       #
-      def list(repo: nil, state: :open, labels: [], page: 1, per_page: 25)
+      def list(**)
+        list_page_info(**).issues
+      end
+
+      # Lists GitHub issues like +.list+, but returns a +PageInfo+ value object carrying the issues plus pagination
+      # metadata read from the response's +Link+ header in the same request. Use this over +.list+ when a caller needs
+      # to know whether more pages exist (e.g. to render "Next"/"Prev" controls) without an optimistic +page + 1+
+      # probe.
+      #
+      # Shares the entire parameter surface, filtering, and PR-rejection behavior of +.list+; see it for semantics.
+      #
+      # Note the PR-filter wart: +per_page+ caps GitHub's raw item count (issues + PRs), but PRs are stripped
+      # client-side afterward, so +page_info.issues.length+ may be smaller than +per_page+. +has_next?+ comes straight
+      # from the +Link+ header, so it reflects raw items too -- a page can report +has_next? == true+ while showing
+      # fewer than +per_page+ issues.
+      #
+      # @raise [ArgumentError] when +priority_list: false+ is passed, or when +issue_type:+ is an Array
+      # @raise [PlanMyStuff::IssueFieldsNotEnabledError] when +issue_fields:+ is passed and
+      #   +config.issue_fields_enabled+ is +false+
+      #
+      # @param repo [Symbol, String, nil] defaults to config.default_repo
+      # @param state [Symbol] :open, :closed, or :all
+      # @param labels [Array<String>]
+      # @param issue_type [String, Symbol, nil] a single GitHub issue type name
+      # @param issue_fields [Hash{String,Symbol => Object,Range,nil}, nil] GitHub Issue Field equality / range filters
+      # @param priority_list [Boolean, nil] when +true+, restricts to +Priority List+ +Yes+ issues
+      # @param page [Integer]
+      # @param per_page [Integer]
+      #
+      # @return [PlanMyStuff::Issue::PageInfo]
+      #
+      def list_page_info(
+        repo: nil,
+        state: :open,
+        labels: [],
+        issue_type: nil,
+        issue_fields: nil,
+        priority_list: nil,
+        page: 1,
+        per_page: 25
+      )
+        if priority_list == false
+          raise(ArgumentError, 'priority_list: false is not supported (no GitHub negation qualifier)')
+        end
+        if issue_fields.present? && !PlanMyStuff.configuration.issue_fields_enabled
+          raise(PlanMyStuff::IssueFieldsNotEnabledError)
+        end
+
         client = PlanMyStuff.client
-        resolved_repo = client.resolve_repo(repo)
+        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.present?
 
-        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
+        resolved_type = resolve_issue_types_filter(issue_type)
+        params[:type] = resolved_type if resolved_type.present?
 
-          build(gi, repo: resolved_repo)
+        field_pairs = []
+        field_pairs.concat(build_issue_field_filter_pairs(issue_fields)) if issue_fields.present?
+        if priority_list && PlanMyStuff.configuration.issue_fields_enabled
+          field_pairs.concat(build_issue_field_filter_pairs('Priority List' => 'Yes'))
         end
+        params[:issue_field_values] = field_pairs.join(',') if field_pairs.present?
+
+        github_issues = client.rest(:list_issues, resolved_repo, **params)
+        rels = client.last_response&.rels || {}
+        filtered = github_issues.reject { |gi| gi.respond_to?(:pull_request) && gi.pull_request }
+
+        PageInfo.new(
+          issues: filtered.map { |gi| build(gi, repo: resolved_repo) },
+          page: page,
+          per_page: per_page,
+          has_next: rels[:next].present?,
+          has_prev: rels[:prev].present?,
+        )
       end
 
-      # Adds user IDs to the visibility allowlist of an issue's metadata.
+      # Convenience shortcut for +list(priority_list: true, ...)+. See +.list+ for parameter semantics.
+      #
+      # @return [Array<PlanMyStuff::Issue>]
+      #
+      def priority_list(**)
+        list(**, priority_list: true)
+      end
+
+      # Counts GitHub issues matching the given filters without paginating full payloads.
+      #
+      # Uses GitHub's Search API (+search/issues+), which returns +total_count+ in a single
+      # request. The +is:issue+ qualifier excludes PRs server-side.
+      #
+      # Caveats:
+      # - The search index lags writes by up to ~1 minute, so freshly created/closed issues
+      #   may not be reflected immediately.
+      # - The Search API has its own rate limit (30 req/min authenticated) separate from
+      #   the core REST API.
+      #
+      # @raise [ArgumentError] when +priority_list: false+ is passed, or when +issue_type:+ is an Array
+      # @raise [PlanMyStuff::IssueFieldsNotEnabledError] when +issue_fields:+ is passed and
+      #   +config.issue_fields_enabled+ is +false+
       #
-      # @param number [Integer]
       # @param repo [Symbol, String, nil] defaults to config.default_repo
-      # @param user_ids [Array<Integer>]
+      # @param state [Symbol] :open, :closed, or :all
+      # @param labels [Array<String>]
+      # @param issue_type [String, Symbol, nil] a single GitHub issue type name. Symbols resolve through
+      #   +ISSUE_TYPE_NICKNAMES+ then +config.issue_types+.
+      # @param issue_fields [Hash{String,Symbol => Object,Range,nil}, nil] GitHub Issue Field equality / range
+      #   filters. See +.list+ for the value shapes the gem accepts. Each pair is emitted as a
+      #   +field.<slug>:<value>+ Search qualifier and triggers +advanced_search=true+.
+      # @param priority_list [Boolean, nil] when +true+, restricts to issues whose +Priority List+ issue field is
+      #   +Yes+ (server-side filter via the +field.priority-list:Yes+ Search qualifier). +false+ raises
+      #   +ArgumentError+ -- GitHub has no negation qualifier. Silently dropped when
+      #   +config.issue_fields_enabled+ is +false+.
+      #
+      # @return [Integer]
+      #
+      def count(repo: nil, state: :open, labels: [], issue_type: nil, issue_fields: nil, priority_list: nil)
+        if priority_list == false
+          raise(ArgumentError, 'priority_list: false is not supported (no GitHub negation qualifier)')
+        end
+        if issue_fields.present? && !PlanMyStuff.configuration.issue_fields_enabled
+          raise(PlanMyStuff::IssueFieldsNotEnabledError)
+        end
+
+        client = PlanMyStuff.client
+        resolved_repo = client.resolve_repo!(repo)
+
+        normalized_state = state.to_s
+        qualifiers = ["repo:#{resolved_repo}", 'is:issue']
+        qualifiers << "is:#{normalized_state}" unless normalized_state == 'all'
+        labels_to_use = Array.wrap(labels).sort
+        qualifiers += labels_to_use.map do |label|
+          "label:\"#{label}\""
+        end
+
+        resolved_type = resolve_issue_types_filter(issue_type)
+        qualifiers << "type:#{resolved_type}" if resolved_type.present?
+
+        field_pairs = []
+        field_pairs.concat(build_issue_field_filter_pairs(issue_fields)) if issue_fields.present?
+        if priority_list && PlanMyStuff.configuration.issue_fields_enabled
+          field_pairs.concat(build_issue_field_filter_pairs('Priority List' => 'Yes'))
+        end
+        qualifiers += field_pairs.map { |pair| "field.#{pair}" }
+
+        search_options = { per_page: 1 }
+        search_options[:advanced_search] = true if field_pairs.present?
+        client.rest(:search_issues, qualifiers.join(' '), **search_options).total_count
+      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.
       #
-      # @return [Object] Octokit response
+      # 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.
       #
-      def add_viewers(number:, user_ids:, repo: nil)
-        modify_allowlist(number: number, repo: repo) do |allowlist|
-          allowlist | Array.wrap(user_ids)
+      # 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
 
-      # Removes user IDs from the visibility allowlist of an issue's metadata.
+      # Polls a previously-submitted import for its current status.
       #
-      # @param number [Integer]
+      # @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
-      # @param user_ids [Array<Integer>]
       #
-      # @return [Object] Octokit response
+      # @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
+
+      # @raise [ArgumentError] when +repo+ resolves to a Repo with no configured key (cannot reverse-resolve through
+      #   +Repo.from_nickname!+, so the resulting token would not round-trip through +Issue.find+ / +from_param+)
+      #
+      # @param number [Integer]
+      # @param repo [String] full repo path, e.g. +"BrandsInsurance/Element"+
       #
-      def remove_viewers(number:, user_ids:, repo: nil)
-        modify_allowlist(number: number, repo: repo) do |allowlist|
-          allowlist - Array.wrap(user_ids)
+      # @return [String]
+      #
+      def to_param(number, repo)
+        return if number.blank?
+        return if repo.blank?
+
+        repo_obj = PlanMyStuff::Repo.resolve!(repo)
+        if repo_obj.key.nil?
+          raise(
+            ArgumentError,
+            "Repo #{repo_obj.full_name.inspect} is not configured in config.repos; " \
+              'cannot build reversible Issue#to_param token',
+          )
         end
+
+        "#{repo_obj.nickname}-#{number}"
+      end
+
+      # Parses an +Issue#to_param+ string of the form +"Nickname-1234"+ back into +[Repo, Integer]+. The repo is
+      # looked up via +PlanMyStuff::Repo.from_nickname!+, which scans +config.repos+ for the key whose
+      # +config.repo_nickname_for+ matches.
+      #
+      # @raise [ArgumentError] when +param+ does not match the +"Prefix-1234"+ shape or the prefix is not a known
+      #   repo nickname
+      #
+      # @param param [String]
+      #
+      # @return [Array(PlanMyStuff::Repo, Integer)]
+      #
+      def from_param(param)
+        match = param.to_s.match(/\A(?<nickname>.+)-(?<number>\d+)\z/)
+        raise(ArgumentError, "Invalid issue param: #{param.inspect}") if match.nil?
+
+        [PlanMyStuff::Repo.from_nickname!(match[:nickname]), match[:number].to_i]
       end
 
       private
 
+        # Splits the +Issue.find+ first arg into +[number, resolved_repo_full_name]+. A nickname-id String like
+        # +"Rawr-1234"+ is decoded via +from_param+ (repo derived from the prefix; +repo:+ kwarg ignored). All other
+        # inputs (Integer, all-digit String) fall through to the existing +client.resolve_repo!+ path with the kwarg.
+        #
+        # @param id_or_number [Integer, String]
+        # @param repo [Symbol, String, PlanMyStuff::Repo, nil]
+        #
+        # @return [Array(Integer, String)]
+        #
+        def resolve_find_args(id_or_number, repo)
+          if id_or_number.is_a?(String) && !id_or_number.match?(/\A\d+\z/)
+            repo_obj, number = from_param(id_or_number)
+            [number, repo_obj.full_name]
+          else
+            [id_or_number.to_i, PlanMyStuff.client.resolve_repo!(repo)]
+          end
+        end
+
+        # 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
+              begin
+                resolve_issue_type!(value.to_sym)
+              rescue ArgumentError
+                value
+              end
+            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
+
+        # Resolves an +issue_type:+ filter kwarg (used by +.list+ / +.count+) into a single canonical type name.
+        # Accepts a scalar (String / Symbol); +nil+ returns +nil+ so callers can skip the filter entirely. Runs
+        # through +resolve_issue_type!+ so symbol nicknames and +config.issue_types+ overrides apply consistently
+        # with +create!+ / +update!+. Arrays raise +ArgumentError+ -- GitHub's REST +type+ param and Search
+        # +type:+ qualifier each accept a single value at a time.
+        #
+        # @raise [ArgumentError] when +value+ is an Array
+        #
+        # @param value [String, Symbol, nil]
+        #
+        # @return [String, nil]
+        #
+        def resolve_issue_types_filter(value)
+          return if value.nil?
+          if value.is_a?(Array)
+            raise(ArgumentError, 'issue_type: must be a single String / Symbol; GitHub does not accept multiple types')
+          end
+
+          resolve_issue_type!(value)
+        end
+
+        # Slugifies a field name into the kebab-case form GitHub expects in +issue_field_values+ and the Search API's
+        # +field.<slug>:+ qualifier (e.g. +"Priority List"+ / +:priority_list+ -> +"priority-list"+). Lowercases and
+        # collapses runs of whitespace or underscores into a single hyphen.
+        #
+        # @param name [String, Symbol]
+        #
+        # @return [String]
+        #
+        def field_filter_slug(name)
+          name.to_s.downcase.gsub(/[\s_]+/, '-')
+        end
+
+        # Coerces an issue-field filter value to the literal string GitHub expects in the query (Date / Time -> ISO
+        # 8601, Numeric / scalar -> +to_s+). Range bounds are handled separately by
+        # +build_issue_field_filter_pairs+.
+        #
+        # @param value [Object]
+        #
+        # @return [String]
+        #
+        def format_field_filter_value(value)
+          case value
+          when Date, Time then value.iso8601
+          else value.to_s
+          end
+        end
+
+        # Expands an +issue_fields:+ kwarg hash into the flat +Array<String>+ of +slug:value+ pairs that both REST
+        # (+issue_field_values=...+) and Search (+field.slug:value...+) consume.
+        #
+        # Scalars become a single equality pair. +Range+ values expand into one or two comparison pairs:
+        # +>=+/+<=+ for inclusive bounds, +<+ for an exclusive end (+...+). Beginless / endless ranges emit only
+        # the bounded side. +nil+ values are skipped.
+        #
+        # @param hash [Hash{String,Symbol => Object,Range,nil}]
+        #
+        # @return [Array<String>]
+        #
+        def build_issue_field_filter_pairs(hash)
+          hash.flat_map do |name, value|
+            slug = field_filter_slug(PlanMyStuff::IssueFieldTranslation.consumer_field_name(name))
+            case value
+            when nil then []
+            when Range then range_field_filter_pairs(slug, value)
+            else
+              consumer_value = PlanMyStuff::IssueFieldTranslation.consumer_value(name, value)
+              ["#{slug}:#{format_field_filter_value(consumer_value)}"]
+            end
+          end
+        end
+
+        # Expands a +Range+ value into the +slug:>=begin+ / +slug:<=end+ (or +<end+ for +...+) pair(s) GitHub expects.
+        #
+        # @param slug [String]
+        # @param range [Range]
+        #
+        # @return [Array<String>]
+        #
+        def range_field_filter_pairs(slug, range)
+          pairs = []
+          pairs << "#{slug}:>=#{format_field_filter_value(range.begin)}" if range.begin.present?
+          if range.end.present?
+            end_op = range.exclude_end? ? '<' : '<='
+            pairs << "#{slug}:#{end_op}#{format_field_filter_value(range.end)}"
+          end
+          pairs
+        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 (in +Issue#to_param+ form, e.g. +"/issues/Rawr-1234"+), 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?
+
+          to_par = to_param(number, repo)
+          url = "#{prefix.to_s.chomp('/')}/#{to_par}"
+          "[#{repo}##{number}](#{url})"
+        end
+
         # Hydrates an Issue from a GitHub API response.
         #
         # @param github_issue [Object] Octokit issue response
@@ -217,41 +775,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
 
-        # 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]
+        # Finds the first PMS comment on an issue and updates its body content, preserving the comment header and
+        # metadata.
         #
-        # @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)
-          existing_metadata[:updated_at] = Time.now.utc.iso8601
-
-          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.
+        # @raise [PlanMyStuff::Error] when the issue has no body comment
         #
         # @param number [Integer] issue number
         # @param resolved_repo [String] resolved repo path
@@ -259,73 +797,169 @@ 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?
 
-          header = body_comment.header
-
-          updated_body =
-            if header.present?
-              "#{header}\n\n#{new_body}"
-            else
-              new_body
-            end
-
-          body_comment.update!(body: updated_body)
+          body_comment.update!(body: new_body)
         end
     end
 
     def initialize(**attrs)
-      @number = attrs.delete(:number)
-      @raw_body = nil
-      @metadata = IssueMetadata.new
+      @body_dirty = false
       super
-      @labels ||= []
     end
 
-    # Persists the issue. Creates if new, updates if persisted.
+    # @param value [PlanMyStuff::Repo, Symbol, String, nil]
+    def repo=(value)
+      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]
     #
-    # @raise [PlanMyStuff::StaleObjectError] on update if stale
+    # @return [String]
+    #
+    def body=(value)
+      super
+      @body_dirty = true
+    end
+
+    # Single-segment URL token combining repo nickname and issue number, used by Rails route helpers
+    # (+youtrack_issue_path(@issue)+ -> +"/issues/Rawr-1234"+). Returns +nil+ for new records or when +number+ or
+    # +repo+ is unset; +Issue.from_param+ parses the same shape back into +[Repo, Integer]+.
+    #
+    # @return [String, nil]
+    #
+    def to_param
+      return if new_record?
+
+      self.class.to_param(number, repo)
+    end
+
+    # @return [String, nil] per-issue URL in the consuming app (+config.issues_url_prefix+ + +"/"+ + +to_param+, or
+    #   +nil+ when prefix, number, or repo 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?
+
+      to_par = to_param
+      return if to_par.blank?
+
+      "#{prefix.to_s.chomp('/')}/#{to_par}"
+    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 +issue_archived.plan_my_stuff+ 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 save!
+    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: PlanMyStuff.format_time(now) },
+      )
+
+      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, 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]
+    #
+    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),
+          issue_type: issue_type,
+          issue_fields: @pending_issue_fields,
         )
         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
 
+      @pending_issue_fields = nil
       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:)
-    #
-    # @raise [PlanMyStuff::StaleObjectError] if remote updated_at differs from local
+    # @param user [Object, nil] actor for notification events
     #
     # @return [self]
     #
-    def update!(**attrs)
-      raise_if_stale!
+    def update!(user: nil, skip_notification: false, **attrs)
+      apply_update_attrs(attrs)
+      save!(user: user, skip_notification: skip_notification)
+    end
+
+    # Stamps +metadata.responded_at+ on the first support-user engagement with this issue. Centralizes the guards so
+    # every engagement path (first support comment, +Pipeline.take!+, self-assign webhook) can funnel through one
+    # method. No-ops unless +user+ resolves to a support user on a PMS issue that hasn't been responded to yet.
+    #
+    # @param user [Object, nil] actor engaging with the issue (resolved via +PlanMyStuff::UserResolver+)
+    #
+    # @return [void]
+    #
+    def mark_responded!(user)
+      resolved = PlanMyStuff::UserResolver.resolve(user)
+      return if resolved.blank?
+
+      return unless PlanMyStuff::UserResolver.support?(resolved)
+      return unless pms_issue?
+
+      return if metadata.responded?
 
       self.class.update!(
         number: number,
         repo: repo,
-        **attrs,
+        metadata: { responded_at: PlanMyStuff.format_time(Time.now.utc) },
       )
-
-      reload
     end
 
     # Re-fetches this issue from GitHub and updates all local attributes.
@@ -346,6 +980,22 @@ 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
+
+    # GitHub assignees for this issue, by login.
+    #
+    # @return [Array<String>]
+    #
+    def assignees
+      extract_assignee_logins(github_response)
+    end
+
     # @return [Boolean]
     def pms_issue?
       metadata.schema_version.present?
@@ -364,36 +1014,118 @@ 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]
     #
     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
+
+    # 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
 
-    # Delegates visibility check to metadata.
-    # Non-PMS issues are always visible.
+    # Returns a hash-like view of GitHub Issue Field values currently set on this issue. Reads on first access and
+    # memoizes; +set_issue_fields!+ invalidates the cache. Returns an empty set without making a request when
+    # +config.issue_fields_enabled+ is +false+.
     #
-    # @param user [Object, Integer] user object or user_id
+    # @return [PlanMyStuff::IssueFieldValueSet]
     #
+    def issue_fields
+      @issue_fields ||= load_issue_fields!
+    end
+
     # @return [Boolean]
+    def priority_list?
+      issue_fields['Priority List'] == 'Yes'
+    end
+
+    # @return [Integer, nil]
+    def priority_list_priority
+      issue_fields['Priority List Priority']
+    end
+
+    # Adds this issue to the Priority List at the given priority (or re-prioritizes if already listed). Sets
+    # +Priority List+ and +Priority List Priority+ together in a single +setIssueFieldValue+ mutation so the two
+    # fields never drift out of sync.
     #
-    def visible_to?(user)
-      if pms_issue?
-        metadata.visible_to?(user)
-      else
-        UserResolver.support?(UserResolver.resolve(user))
+    # @raise [PlanMyStuff::IssueFieldsNotEnabledError] when +config.issue_fields_enabled+ is +false+
+    #
+    # @param priority [Integer]
+    #
+    # @return [self]
+    #
+    def add_to_priority_list!(priority:)
+      raise(ArgumentError, 'Priority must be an integer') unless priority.is_a?(Integer)
+
+      set_issue_fields!('Priority List' => 'Yes', 'Priority List Priority' => priority)
+    end
+
+    alias update_priority_list_priority! add_to_priority_list!
+
+    # Removes this issue from the Priority List. Clears both +Priority List+ and +Priority List Priority+ in a single
+    # +setIssueFieldValue+ mutation so the two fields never drift out of sync.
+    #
+    # @raise [PlanMyStuff::IssueFieldsNotEnabledError] when +config.issue_fields_enabled+ is +false+
+    #
+    # @return [self]
+    #
+    def remove_from_priority_list!
+      set_issue_fields!('Priority List' => nil, 'Priority List Priority' => nil)
+    end
+
+    # Bulk-updates GitHub Issue Field values in a single +setIssueFieldValue+ mutation. Each key is the field display
+    # name; values are coerced to the right input fragment based on the field's type. Passing +nil+ as a value clears
+    # that field.
+    #
+    # @raise [PlanMyStuff::IssueFieldsNotEnabledError] when +config.issue_fields_enabled+ is +false+
+    # @raise [PlanMyStuff::Error] when a referenced field name does not exist on the org
+    #
+    # @param updates [Hash{String,Symbol => Object,nil}]
+    #
+    # @return [self]
+    #
+    def set_issue_fields!(updates)
+      raise(PlanMyStuff::IssueFieldsNotEnabledError) unless PlanMyStuff.configuration.issue_fields_enabled
+
+      fields_by_name = PlanMyStuff::IssueField.list(org: repo.organization).index_by { |field| field.name.downcase }
+      inputs = updates.map do |name, value|
+        build_issue_field_input(
+          fields_by_name,
+          PlanMyStuff::IssueFieldTranslation.consumer_field_name(name),
+          PlanMyStuff::IssueFieldTranslation.consumer_value(name, value),
+        )
       end
+
+      PlanMyStuff.client.graphql(
+        PlanMyStuff::GraphQL::Queries::SET_ISSUE_FIELD_VALUES,
+        variables: { issueId: github_node_id, issueFields: inputs },
+      )
+
+      @issue_fields = nil
+      self
     end
 
     private
@@ -406,18 +1138,27 @@ module PlanMyStuff
       # @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) || ''
-        @labels = extract_labels(github_issue)
-        @repo = repo
-
-        parsed = MetadataParser.parse(@raw_body)
-        @metadata = IssueMetadata.from_hash(parsed[:metadata])
-        @body = parsed[:body]
-        @persisted = true
+        @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.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 = PlanMyStuff::MetadataParser.parse(raw_body)
+        self.metadata = PlanMyStuff::IssueMetadata.from_hash(parsed[:metadata])
+        self.body = parsed[:body]
+        @body_dirty = false
+        persisted!
         @comments = nil
+        @issue_fields = nil
+        invalidate_links_cache!
       end
 
       # Copies attributes from another Issue instance into self.
@@ -427,20 +1168,110 @@ module PlanMyStuff
       # @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
-        @labels = other.labels
-        @repo = other.repo
-        @metadata = other.metadata
-        @persisted = true
+        @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.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!
         @comments = nil
+        @issue_fields = nil
+        invalidate_links_cache!
+      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
+
+      # 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]
+      #
+      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?
+        attrs[:issue_fields] = @pending_issue_fields if @pending_issue_fields.present?
+        attrs[:issue_type] = issue_type if issue_type_changed?
+
+        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)
+        self.issue_type = attrs[:issue_type] if attrs.key?(:issue_type)
+        @pending_assignees = attrs[:assignees] if attrs.key?(:assignees)
+        @pending_issue_fields = attrs[:issue_fields] if attrs.key?(:issue_fields)
+        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.
+      # Raises StaleObjectError if the remote issue has been modified since this instance was loaded.
       #
       # @raise [PlanMyStuff::StaleObjectError]
       #
@@ -448,20 +1279,22 @@ module PlanMyStuff
       #
       def raise_if_stale!
         return if new_record?
-        return if metadata.updated_at.nil?
+        return if updated_at.nil?
 
         remote = self.class.find(number, repo: repo)
-        remote_time = remote.metadata.updated_at
-        local_time = metadata.updated_at
+        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,
-        ))
+        raise(
+          PlanMyStuff::StaleObjectError.new(
+            "Issue ##{number} has been modified remotely",
+            local_updated_at: local_time,
+            remote_updated_at: remote_time,
+          ),
+        )
       end
 
       # @return [Array<String>]
@@ -470,6 +1303,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)
@@ -480,7 +1325,93 @@ module PlanMyStuff
 
       # @return [Array<PlanMyStuff::Comment>]
       def load_comments
-        Comment.list(issue: self)
+        PlanMyStuff::Comment.list(issue: self)
+      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
+
+      # @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::IssueFieldValueSet]
+      def load_issue_fields!
+        return PlanMyStuff::IssueFieldValueSet.new({}) unless PlanMyStuff.configuration.issue_fields_enabled
+
+        data = PlanMyStuff.client.graphql(
+          PlanMyStuff::GraphQL::Queries::READ_ISSUE_FIELD_VALUES,
+          variables: { owner: repo.organization, name: repo.name, number: number },
+        )
+        nodes = data.dig(:repository, :issue, :issueFieldValues, :nodes)
+        PlanMyStuff::IssueFieldValueSet.from_graphql(nodes)
+      end
+
+      # Builds one element of the +issueFields+ argument to the +setIssueFieldValue+ mutation. Looks up the field
+      # definition in the provided hash to pick the right input fragment and (for single-select) resolve the option ID.
+      #
+      # @raise [PlanMyStuff::Error] if the field name is unknown on the org
+      #
+      # @param fields_by_name [Hash{String => PlanMyStuff::IssueField}] fields keyed by downcased display name
+      # @param name [String, Symbol]
+      # @param value [Object, nil]
+      #
+      # @return [Hash]
+      #
+      def build_issue_field_input(fields_by_name, name, value)
+        field = fields_by_name[name.to_s.downcase]
+        raise(PlanMyStuff::Error, "Unknown Issue Field #{name.inspect}") if field.nil?
+
+        return { fieldId: field.id, delete: true } if value.nil?
+
+        case field.type
+        when :single_select then { fieldId: field.id, singleSelectOptionId: field.option_id_for!(value) }
+        when :date then { fieldId: field.id, dateValue: value.to_date.iso8601 }
+        when :number
+          unless value.is_a?(Numeric)
+            raise(PlanMyStuff::Error, "Issue Field #{name.inspect} expects Numeric, got #{value.inspect}")
+          end
+
+          { fieldId: field.id, numberValue: value.to_f }
+        when :text then { fieldId: field.id, textValue: value.to_s }
+        end
       end
   end
 end