plan_my_stuff 0.1.0 → 1.0.0

data/README.md

@@ -9,15 +9,6 @@ A Rails engine gem that provides a GitHub-backed ticketing and project tracking
 
 **Ruby:** >= 3.3 | **Rails:** >= 6.1, < 8 | **API client:** Octokit
 
-> [!IMPORTANT]
-> **commonmarker version compatibility:** This gem requires commonmarker v1.0+ (pinned `~> 2.7`). The v0.23 to v1.0 upgrade was a full rewrite with breaking changes:
-> - Module renamed: `CommonMarker` to `Commonmarker`
-> - Methods renamed: `render_html` to `to_html`, `render_doc` to `parse`
-> - Options changed from array of symbols (`[:HARDBREAKS]`) to nested hash (`options: { render: { hardbreaks: true } }`)
-> - Underlying engine changed from C (libcmark-gfm) to Rust (comrak)
->
-> If your app already uses commonmarker < 1.0, you will need to upgrade. Alternatively, configure `markdown_renderer = :redcarpet` or `nil` to avoid the dependency entirely.
-
 ## Installation
 
 Add to your Gemfile:
@@ -51,6 +42,9 @@ The gem supports three markdown rendering options. The chosen gem must be in you
 | redcarpet | `gem 'redcarpet'` | `config.markdown_renderer = :redcarpet` |
 | None (raw) | Nothing | `config.markdown_renderer = nil` |
 
+> [!NOTE]
+> If you pick `:commonmarker`, use v1.0+ — the v0.23 -> v1.0 rewrite renamed the module to `Commonmarker`, swapped `render_html` for `to_html`, and moved options from a symbol array to a nested hash. Apps still on commonmarker < 1.0 must upgrade or switch to `:redcarpet` / `nil`.
+
 ### Overriding views
 
 Copy the default views into your app for customization:
@@ -61,61 +55,57 @@ rails generate plan_my_stuff:views
 
 ## Configuration
 
-```ruby
-# config/initializers/plan_my_stuff.rb
-PlanMyStuff.configure do |config|
-  # Auth (PAT from a bot account with repo + project scopes)
-  config.access_token = ENV['PMS_GITHUB_TOKEN']
+The install generator drops a fully-commented initializer at
+`config/initializers/plan_my_stuff.rb`. Two options are required:
 
-  # Organization
+```ruby
+PMS.configure do |config|
+  config.access_token = Rails.application.credentials.dig(:plan_my_stuff, :github_token)
   config.organization = 'YourOrganization'
+end
+```
 
-  # Named repo configs
-  config.repos[:marketing_website] = 'YourOrganization/MarketingWebsite'
-  config.repos[:cms_website] = 'YourOrganization/CMSWebsite'
-  config.default_repo = :cms_website
+Everything else is optional. See [CONFIGURATION.md](CONFIGURATION.md) for the
+full option reference grouped by concern (repos, projects, user
+integration, markdown, request gateway, custom fields, pipeline,
+reminders, archiving, AWS webhook, caching, routes, controllers).
 
-  # Default project board
-  config.default_project_number = 123
+The `PMS` alias is available for brevity: `PMS.configure`, `PMS::Issue.find`, etc.
 
-  # User class (your app's model)
-  config.user_class = 'User'
-  config.display_name_method = :full_name
-  config.user_id_method = :id
+## Architecture
 
-  # Support role check (symbol or proc)
-  config.support_method = :support?
+All state lives on GitHub. The gem exposes it through ActiveRecord-style domain objects that call the GitHub REST and GraphQL APIs under the hood.
 
-  # Markdown rendering (:commonmarker, :redcarpet, or nil)
-  config.markdown_renderer = :commonmarker
+### Domain class hierarchy
 
-  # Request gateway (proc or nil; nil = always send)
-  config.should_send_request = nil
+```text
+ApplicationRecord                 # includes ActiveModel::Model, Attributes, Serializers::JSON
+├── Issue                         # GitHub Issue
+├── Comment                       # GitHub Issue comment
+├── Label                         # GitHub Label
+├── BaseProject                   # shared GraphQL hydration for Projects V2
+│   ├── Project                   # regular project board (metadata.kind == "project")
+│   └── TestingProject            # testing/QA board (metadata.kind == "testing")
+└── BaseProjectItem               # shared item behaviour
+    ├── ProjectItem
+    └── TestingProjectItem        # adds pass/fail sign-off logic
+```
 
-  # Background jobs (when gateway defers a request)
-  config.job_classes = {
-    create_ticket: 'PmsCreateTicketJob',
-    post_comment:  'PmsPostCommentJob',
-    update_status: 'PmsUpdateStatusJob'
-  }
+### AR-style API
 
-  # Deferred request notifications
-  config.deferred_notifier = nil
-  config.deferred_email_from = 'noreply@example.com'
-  config.deferred_email_to   = 'support@example.com'
+Every domain class exposes the same surface:
 
-  # Custom fields (stored in issue/comment metadata)
-  config.custom_fields = {
-    ticket_type: { type: :string },
-    notification_recipients: { type: :array }
-  }
+| Class method | Instance method | Notes |
+|---|---|---|
+| `.find(id, ...)` | `#reload`, `#raise_if_stale!` | single read |
+| `.list(...)` | — | list read |
+| `.create!(attrs)` | — | write + fires `*.created` event |
+| — | `#save!`, `#update!(attrs)` | write + fires `*.updated` event |
+| — | `#persisted?`, `#new_record?`, `#destroyed?` | state predicates |
 
-  # App name (appears in metadata)
-  config.app_name = 'MyApp'
-end
-```
+Issues and comments are never hard-deleted (GitHub keeps them forever) — `Issue#update!(state: :closed)` and the archive workflow handle lifecycle instead. `ProjectItem#destroy!` and `TestingProjectItem#destroy!` remove items from a board.
 
-The `PMS` alias is available for brevity: `PMS.configure`, `PMS::Issue.find`, etc.
+Every mutating method accepts `user:` so notifications know the actor; falls back to `config.current_user.call` if omitted.
 
 ## Usage
 
@@ -133,10 +123,10 @@ issue = PMS::Issue.create!(
 )
 
 # Find
-issue = PMS::Issue.find(repo: :cms_website, number: 123)
+issue = PMS::Issue.find(123, repo: :cms_website)
 issue.title
 issue.body              # body without metadata
-issue.metadata          # PlanMyStuff::IssueMetadata
+issue.metadata          # PMS::IssueMetadata
 issue.visible_to?(user) # visibility check
 issue.comments          # all comments
 issue.pms_comments      # only PMS-created comments
@@ -152,28 +142,63 @@ issue.update!(state: :closed)
 issue.update!(state: :open)
 
 # Viewer management (visibility allowlist)
-PMS::Issue.add_viewers(repo: :cms_website, number: 123, user_ids: [5, 12])
-PMS::Issue.remove_viewers(repo: :cms_website, number: 123, user_ids: [5])
+issue.add_viewers!(user_ids: [5, 12], user: current_user)
+issue.remove_viewers!(user_ids: [5], user: current_user)
+```
+
+#### Importing existing issues
+
+`PMS::Issue.import!` wraps GitHub's "Import Issues" preview endpoint. It takes an array of GitHub-shaped payloads (one POST per payload) and returns one status hash per input. Payloads are passed through unchanged except for `:repo`, which is extracted to build the request URL.
+
+> [!CAUTION]
+> If you choose to use `PMS::Issue.import!`/`PMS::Issue.check_import!`, you must configure `import_access_token`
+
+```ruby
+payloads = [
+  {
+    repo: :cms_website,
+    issue: {
+      title:      '[Rawr-12517] Delete contractor check payment',
+      body:       "Imported from YouTrack...",
+      labels:     ['imported-from-youtrack', 'priority:normal'],
+      created_at: '2026-04-28T16:04:59Z',
+    },
+    comments: [
+      { body: 'first comment',  created_at: '2026-04-28T16:26:08Z' },
+      { body: 'second comment', created_at: '2026-04-28T16:26:29Z' },
+    ],
+  },
+]
+
+statuses = PMS::Issue.import!(payloads)
+status   = PMS::Issue.check_import!(statuses.first[:id], repo: :cms_website)
+# => { id: ..., status: 'imported', issue_url: '.../issues/123' }
 ```
 
+Notes:
+
+- Each payload MUST include `:repo` (symbol, string, or `PMS::Repo`); a missing `:repo` raises `ArgumentError`.
+- The gem does not embed PMS metadata into the payload — callers are responsible for any metadata or formatting they want to preserve from the source system.
+- The endpoint is async: `import` returns `{ id:, status: 'pending', url: ... }`; poll `check_import` until `status` is `'imported'` or `'failed'`.
+- Requires a classic GitHub PAT with the `repo` scope; fine-grained tokens are rejected with 403.
+
 ### Comments
 
 ```ruby
 # Create
 comment = PMS::Comment.create!(
-  repo: :cms_website,
-  issue_number: 123,
+  issue: issue,
   body: 'Deployed fix to staging, please retest.',
   user: current_user,
   visibility: :public   # or :internal (support-only)
 )
 
 # List
-comments = PMS::Comment.list(repo: :cms_website, issue_number: 123)
-comments = PMS::Comment.list(repo: :cms_website, issue_number: 123, pms_only: true)
+comments = PMS::Comment.list(issue: issue)
+comments = PMS::Comment.list(issue: issue, pms_only: true)
 
 comment.body            # visible text
-comment.metadata        # PlanMyStuff::CommentMetadata (nil for non-PMS comments)
+comment.metadata        # PMS::CommentMetadata (nil for non-PMS comments)
 comment.visibility      # :public, :internal, or nil
 comment.pms_comment?    # true/false
 comment.visible_to?(user)
@@ -182,8 +207,8 @@ comment.visible_to?(user)
 ### Labels
 
 ```ruby
-PMS::Label.add(repo: :cms_website, issue_number: 123, labels: ['in-progress'])
-PMS::Label.remove(repo: :cms_website, issue_number: 123, labels: ['triage'])
+PMS::Label.add!(issue: issue, labels: ['in-progress'])
+PMS::Label.remove!(issue: issue, labels: ['triage'])
 ```
 
 ### Projects
@@ -206,21 +231,494 @@ item.move_to!('In Review')
 item.assign!('octocat')
 
 # Add existing issue to project
-PMS::Project.add_item(project_number: 14, issue_repo: :cms_website, issue_number: 123)
+PMS::ProjectItem.create!(issue, project_number: 14)
 
 # Add draft item
-PMS::Project.add_draft_item(project_number: 14, title: 'Draft task', body: 'Details...')
+PMS::ProjectItem.create!('Draft task', draft: true, body: 'Details...', project_number: 14)
+```
+
+### Testing tracking
+
+`TestingProject` and `TestingProjectItem` are a specialisation of the project classes for manual QA sign-off. A testing project is a GitHub Projects V2 board stamped with `metadata.kind == "testing"` and a fixed set of single-select and text fields (Test Status, Testers, Watchers, Pass Mode, Due Date, Deadline Miss Reason, Result Notes, Passed By, Failed By, Passed At).
+
+Create a board — either bootstrap fields from scratch, or clone the board configured at `config.testing_template_project_number`:
+
+```ruby
+project = PMS::TestingProject.create!(
+  title:      'Release 2026.05 manual QA',
+  user:       current_user,
+  subject_urls: ['https://github.com/Org/Repo/pull/421'],
+  due_date:     Date.parse('2026-05-10'),
+)
+```
+
+Per-item sign-off:
+
+```ruby
+item = project.items.first
+item.update_pass_mode!('all')                            # or 'any'
+item.update_testers!([alice.id, bob.id])
+item.update_watchers!([carol.id])
+item.mark_passed!(alice)                                 # flips to Passed when Pass Mode is satisfied
+item.mark_failed!(alice, result_notes: 'Reproduced on Safari 17')
+```
+
+A board and its items are editable through the mounted UI at `/testing_projects`.
+
+## Notifications
+
+Every PMS lifecycle write fires an `ActiveSupport::Notifications` event under the `*.plan_my_stuff` namespace
+(Rails convention - event first, library suffix; matches `sql.active_record`, `process_action.action_controller`).
+Subscribe to drive email, webhooks, Slack, ActiveJob, etc. Events fire synchronously (no delays) - subscribers
+that need to defer work should wrap in a background job themselves.
+
+### Event catalog
+
+| Event | Fired from |
+|-------|------------|
+| `issue_created.plan_my_stuff` | `Issue.create!` |
+| `issue_updated.plan_my_stuff` | `issue.save!` / `issue.update!` (any non-state change) |
+| `issue_closed.plan_my_stuff` | `issue.update!(state: :closed)` |
+| `issue_reopened.plan_my_stuff` | `issue.update!(state: :open)` |
+| `issue_viewers_added.plan_my_stuff` | `issue.add_viewers!` |
+| `issue_viewers_removed.plan_my_stuff` | `issue.remove_viewers!` |
+| `issue_approval_requested.plan_my_stuff` | `issue.request_approvals!` |
+| `issue_approval_granted.plan_my_stuff` | `issue.approve!` |
+| `issue_approval_revoked.plan_my_stuff` | `issue.revoke_approval!` |
+| `issue_all_approved.plan_my_stuff` | aggregate; fires when the set flips to fully approved |
+| `issue_approvals_invalidated.plan_my_stuff` | aggregate; fires on revoke or new approver dropping the set |
+| `comment_created.plan_my_stuff` | `Comment.create!` |
+| `comment_updated.plan_my_stuff` | `comment.save!` / `comment.update!` |
+| `label_added.plan_my_stuff` | `Label.add!` |
+| `label_removed.plan_my_stuff` | `Label.remove!` |
+| `project_item_added.plan_my_stuff` | `ProjectItem.create!` (issue or `draft: true`) |
+| `project_item_removed.plan_my_stuff` | `project_item.destroy!` |
+| `project_item_assigned.plan_my_stuff` | `project_item.assign!` |
+| `project_item_status_changed.plan_my_stuff` | `project_item.move_to!` |
+
+### Payload
+
+All events include:
+
+- `:<resource>` — the domain object (`:issue`, `:comment`, `:project_item`)
+- `:user` — the actor (see below)
+- `:timestamp` — `Time.current`
+- `:visibility` and `:visibility_allowlist` — present for `Issue` and `Comment` events
+
+Additional keys by event:
+
+- `issue_updated` / `comment_updated` -> `:changes` -- hash of `{ attr => [old, new] }`
+- `issue_viewers_added` / `issue_viewers_removed` -> `:user_ids`
+- `issue_approval_requested` -> `:approvals` (array of newly-added `PMS::Approval`)
+- `issue_approval_granted` / `issue_approval_revoked` -> `:approval` (the flipped `PMS::Approval`)
+- `issue_approvals_invalidated` -> `:trigger` -- `:revoked` or `:approver_added`
+- `label_added` / `label_removed` -> `:labels`
+- `project_item_assigned` -> `:assignees`
+- `project_item_status_changed` -> `:status`, `:previous_status`
+
+### Actor resolution
+
+The `:user` payload key is populated in this precedence:
+
+1. `user:` kwarg passed to the mutating method (e.g. `issue.update!(title: 'x', user: alice)`)
+2. `config.current_user` proc/lambda, if set (called at event time)
+3. `nil`
+
+Use `config.current_user = -> { Current.user }` so request-scoped code doesn't have to thread `user:` everywhere.
+
+### Subscribing
+
+```ruby
+# config/initializers/plan_my_stuff_subscribers.rb
+ActiveSupport::Notifications.subscribe(/\.plan_my_stuff\z/) do |name, _start, _finish, _id, payload|
+  PmsEventMailer.dispatch(name, payload).deliver_later
+end
+```
+
+### Testing subscribers
+
+```ruby
+require 'plan_my_stuff/test_helpers'
+
+# Block-style matcher
+expect {
+  PMS::Issue.create!(title: 'Bug', body: 'Desc', user: alice)
+}.to(have_fired_event('issue_created.plan_my_stuff').with(user: alice))
+
+# Raw capture
+events = PMS::TestHelpers::Notifications.capture do
+  PMS::Issue.create!(...)
+end
+events.first[:name]    # => "issue_created.plan_my_stuff"
+events.first[:payload] # => { issue:, user:, timestamp:, ... }
+```
+
+## Approvals
+
+Manager-approval workflow on issues. Support users request approvals from one or more users; while any approval is pending, forward `PMS::Pipeline` transitions raise `PMS::PendingApprovalsError`. State is stored as a hidden array on `IssueMetadata.approvals` — no extra tables, no GitHub-side schema.
+
+### Writing
+
+```ruby
+issue = PMS::Issue.find(123, repo: :cms_website)
+
+# Support adds required approvers (idempotent; rejects duplicates silently)
+issue.request_approvals!(user_ids: [alice.id, bob.id], user: current_user)
+
+# An approver grants their own approval
+issue.approve!(user: alice)
+
+# An approver revokes their own approval; support may revoke on another's behalf
+issue.revoke_approval!(user: alice)
+issue.revoke_approval!(user: support_user, target_user_id: alice.id)
+
+# Support removes approvers
+issue.remove_approvers!(user_ids: [alice.id], user: current_user)
+```
+
+### Reading
+
+```ruby
+issue.approvers            # Array<PMS::Approval> — all records (pending + approved)
+issue.pending_approvals    # subset still pending
+issue.approvals_required?  # true iff approvers.present?
+issue.fully_approved?      # true iff approvals_required? && pending_approvals.empty?
+```
+
+### Pipeline gating
+
+`PMS::PendingApprovalsError` is raised when any pending approval exists on the linked issue. Gated transitions:
+
+- `Pipeline.take!`
+- `Pipeline.mark_in_review!`
+- `Pipeline.request_testing!`
+- `Pipeline.mark_ready_for_release!`
+
+`Pipeline.remove!`, `start_deployment!`, and `complete_deployment!` are intentionally NOT gated (reverse / batch / CI-driven transitions).
+
+### Events
+
+See the notifications catalog above — `approval_requested`, `approval_granted`, `approval_revoked`, `all_approved`, `approvals_invalidated`. Aggregate events fire after the matching granular event on the same write.
+
+### Testing
+
+```ruby
+require 'plan_my_stuff/test_helpers'
+
+# Build an issue with some approvals already in place (no API call)
+issue = PMS::TestHelpers.build_issue
+PMS::TestHelpers.stub_approvals(issue, approved: [alice], pending: [bob])
+
+issue.fully_approved?      # false
+issue.pending_approvals    # [PMS::Approval(user_id: bob.id, status: 'pending')]
+```
+
+## Reminders
+
+Follow-up reminders for issues waiting on an end-user reply or pending approvers. A daily sweep fires
+`issue_reminder_due.plan_my_stuff` events on waiting issues whose next milestone has passed; issues that exceed the
+inactivity ceiling are auto-closed.
+
+### Waiting on user
+
+A support user enters an issue into "waiting on user" state by either:
+
+1. Posting a comment with `waiting_on_reply: true`:
+
+   ```ruby
+   PMS::Comment.create!(
+     issue: issue,
+     body: "Can you confirm the date range?",
+     user: current_user,
+     waiting_on_reply: true,
+   )
+   ```
+
+2. Clicking the **Mark waiting** button on the mounted issue show page.
+
+Both paths add the `waiting-on-user` label, set `issue.metadata.waiting_on_user_at = now`, and schedule the first reminder.
+
+When an end-user posts a comment through the gem, the label is removed and the waiting state clears. If the issue had
+been auto-closed for inactivity, the reply also reopens it and fires `issue_reopened_by_reply.plan_my_stuff`.
+
+### Waiting on approval
+
+Whenever the pending-approval count goes from zero to one (via `issue.request_approvals!` or `issue.revoke_approval!`), the gem adds the `waiting-on-approval` label and sets `issue.metadata.waiting_on_approval_at = now`. When all pending approvers respond or are removed, the label and timestamp clear automatically.
+
+### Reminder schedule
+
+Reminders fire at specific day counts since waiting started:
+
+```ruby
+config.reminder_days = [1, 3, 7, 10, 14, 18]    # default
+```
+
+Override per-issue:
+
+```ruby
+issue.metadata.reminder_days = [2, 5, 9]
+issue.save!
+```
+
+Each reminder emits `issue_reminder_due.plan_my_stuff` with payload:
+
+| Field | Type | Notes |
+|---|---|---|
+| `issue` | `PMS::Issue` | the waiting issue |
+| `waiting_kind` | `:user` or `:approval` | which clock drove the reminder |
+| `days_waiting` | Integer | days since the waiting clock started |
+| `reminder_day` | Integer | the matched entry in `reminder_days` |
+| `last_activity_at` | Time | last comment or `issue.updated_at` (informational) |
+| `pending_approvers` | `Array<User>` | resolved via `UserResolver`; only for `:approval` |
+
+Subscribe in your app to deliver (email, Slack, etc.):
+
+```ruby
+ActiveSupport::Notifications.subscribe('issue_reminder_due.plan_my_stuff') do |event|
+  issue = event.payload[:issue]
+  case event.payload[:waiting_kind]
+  when :user     then NotifyUserMailer.reminder(issue).deliver_later
+  when :approval then NotifyApproversMailer.reminder(issue, event.payload[:pending_approvers]).deliver_later
+  end
+end
 ```
 
+### Inactivity auto-close
+
+When an issue's `days_waiting` reaches `config.inactivity_close_days` (default 30), the sweep:
+
+- Closes the issue
+- Sets `issue.metadata.closed_by_inactivity = true`
+- Adds the `user-inactive` label (configurable via `config.user_inactive_label`)
+- Emits `issue_closed_inactive.plan_my_stuff` (with `reason: :inactivity`); the regular `issue_closed` event is
+  suppressed so subscribers listening to "close" don't double-fire for automated closes
+
+An end-user reply on a `closed_by_inactivity` issue auto-reopens it, strips the `user-inactive` label, and fires
+`issue_reopened_by_reply.plan_my_stuff`.
+
+### Scheduling the sweep
+
+The gem ships `PMS::RemindersSweepJob`, an ActiveJob that walks a repo's waiting issues and dispatches reminders + auto-closes. Each job self-requeues after perform (default cadence: 6:30am ET next day), so you only need to kick off the initial enqueue — a rake task handles that:
+
+```bash
+# Enqueue one job per configured repo:
+rake plan_my_stuff:reminders:sweep
+
+# Or target a single repo:
+rake plan_my_stuff:reminders:sweep REPO=element
+```
+
+You can also schedule from Ruby if you prefer:
+
+```ruby
+PMS::RemindersSweepJob.requeue(:your_repo_key)  # schedules for next_run
+```
+
+`retry_on StandardError, attempts: 1` prevents geometric duplicate pile-up on Delayed-style adapters — if perform raises, the follow-up run (already enqueued by the `around_perform` ensure) picks up tomorrow.
+
+Override the cadence by subclassing:
+
+```ruby
+class MyRemindersJob < PMS::RemindersSweepJob
+  def self.next_run
+    4.hours.from_now.utc  # run every 4 hours
+  end
+end
+```
+
+### Disabling
+
+```ruby
+config.reminders_enabled = false
+```
+
+The sweep becomes a no-op but still self-requeues so re-enabling doesn't require manual intervention.
+
+## Auto-archiving
+
+Closed PMS issues that have aged past `config.archive_closed_after_days` (default 90) are archived by the daily sweep. Archive means:
+
+1. Tag the issue with `config.archived_label` (default `archived`).
+2. Lock the conversation on GitHub (no new comments).
+3. Remove the issue from every Projects V2 board it sits on.
+4. Stamp `metadata.archived_at`.
+5. Emit `issue_archived.plan_my_stuff` with `reason: :aged_closed`.
+
+The sweep runs inside `PMS::RemindersSweepJob` alongside the follow-up reminders sweep — same cadence, same rake task.
+
+### Exclusions
+
+- **Non-PMS issues** (no `pms-metadata` marker) are skipped — the gem only archives what it created.
+- **Inactivity-closed issues** (`metadata.closed_by_inactivity == true`) are skipped — `T-051` already handled the close.
+- **Already-archived issues** (`metadata.archived_at` set or archived label present) are skipped.
+
+### Manual archive
+
+```ruby
+issue = PMS::Issue.find(123)
+issue.archive!
+```
+
+No-op if the issue is open, already archived, or already carries the archived label.
+
+### Config
+
+```ruby
+config.archiving_enabled = true
+config.archive_closed_after_days = 90
+config.archived_label = 'archived'
+```
+
+Locked issues reject new comments through the gem: `PMS::Comment.create!` raises `PMS::LockedIssueError` when `issue.locked?` is true. The mounted comments controller catches this and redirects back to the issue show with an error flash.
+
+### Subscribing
+
+```ruby
+ActiveSupport::Notifications.subscribe('issue_archived.plan_my_stuff') do |event|
+  issue = event.payload[:issue]
+  ArchiveMailer.notify(issue).deliver_later
+end
+```
+
+### Disabling
+
+```ruby
+config.archiving_enabled = false
+```
+
+Reminders keep running; only the archive pass is suppressed.
+
+## Caching
+
+Read-heavy endpoints cache through `Rails.cache` with HTTP ETags. When the cache has a stored ETag, the gem sends it as `If-None-Match`; GitHub replies 304 and the cached payload is reused (one HTTP round-trip, zero quota spend on the "primary rate limit").
+
+| Cached | Method |
+|---|---|
+| `Issue.find`, `Issue.list` | ETag |
+| `Comment.find`, `Comment.list` | ETag |
+| `Project.find`, `ProjectItem` reads | not cached (GraphQL, no HTTP ETag — deferred) |
+
+Writes front-load the cache: `Issue.create!` / `Issue#update!` / `Label.add` / `Label.remove` / `Comment.create!` / `Comment#update!` all write the fresh payload (and bust affected list caches) so the next read is already warm. Label changes bust the parent issue's cache since labels arrive embedded in the issue payload.
+
+### Configuration
+
+```ruby
+config.cache_enabled = true     # default; set false to bypass entirely
+config.cache_version = 'v2'     # opaque string baked into every cache key;
+                                # bump to orphan all cached entries after deploy
+```
+
+Cache keys include both the gem's `CACHE_VERSION` ("v1") and `config.cache_version`, so gem upgrades and app-side invalidations are independent.
+
 ## Metadata
 
-All state lives on GitHub. Issue and comment metadata is stored as a hidden HTML comment on the first line of the body:
+All state lives on GitHub. Each domain class carries a typed metadata object embedded in the corresponding GitHub
+body (issue/comment body, project readme) as a collapsible `<details>` block containing a JSON code fence, which
+GitHub renders in-page:
+
+````markdown
+<details><summary>pms-metadata</summary>
+
+```json
+{"schema_version":1,"gem_version":"0.0.0","app_name":"MyApp", ...}
+```
+
+</details>
+````
+
+`MetadataParser` strips the block out of the raw body on read and re-inserts it on write — callers see `issue.body` (human text) and `issue.metadata` (typed object) separately.
+
+### Metadata classes
+
+| Class | Stored on | Notable fields |
+|---|---|---|
+| `IssueMetadata` | Issue body | `approvals`, `links`, `waiting_on_user_at`, `waiting_on_approval_at`, `next_reminder_at`, `visibility_allowlist`, `commit_sha`, `auto_complete`, `archived_at`, `closed_by_inactivity`, `custom_fields` |
+| `CommentMetadata` | Comment body | `issue_body` (marks the issue's body-comment), `custom_fields` |
+| `ProjectMetadata` | Project readme | `kind: "project"` |
+| `TestingProjectMetadata` | Testing project readme | `kind: "testing"`, `subject_urls`, `due_date`, `deadline_miss_reason` |
+| `ProjectItemMetadata` | — | minimal; reserved for future fields |
+
+All metadata classes share `schema_version`, `gem_version`, `app_name`, `created_by`, `visibility`, and `custom_fields` via `BaseMetadata`.
+
+### Custom fields
+
+`custom_fields` is the escape hatch for app-specific data. Declare a schema in the initializer:
+
+```ruby
+PlanMyStuff.configure do |config|
+  # Shared across everything that has custom_fields
+  config.custom_fields = {
+    ticket_type: { type: :string, required: true },
+  }
+
+  # Resource-specific (merged on top of shared)
+  config.issue_custom_fields   = { notification_recipients: { type: :array } }
+  config.comment_custom_fields = { internal_note: { type: :boolean } }
+  config.project_custom_fields = { team: { type: :string } }
+  config.testing_custom_fields = { test_plan_url: { type: :string } }
+end
+```
 
-```html
-<!-- pms-metadata:{"gem_version":"0.0.0","app_name":"MyApp","created_at":"2026-03-24T10:00:00Z",...} -->
+Access by name or hash:
+
+```ruby
+issue.metadata.custom_fields.ticket_type          # method-style
+issue.metadata.custom_fields[:ticket_type] = 'bug'
+issue.save!                                       # validates; raises ActiveModel::ValidationError
 ```
 
-This is invisible when rendered on GitHub and parsed automatically by the gem into typed objects (`PMS::IssueMetadata`, `PMS::CommentMetadata`).
+## Release pipeline
+
+`PMS::Pipeline` is a seven-stage state machine that lives on a GitHub Projects V2 board — your code drives transitions, webhooks automate them, and each step fires a notification event.
+
+### Statuses
+
+`PMS::Pipeline::Status::ALL` (in order): `Started` -> `In Review` -> `Ready for Release` -> `Release in Progress` -> `Completed`. (Testing runs orthogonally as a separate single-select field flipped by `request_testing!`, not as a Status value.)
+
+Display names can be overridden in the consuming app via `config.pipeline_statuses`; the constants above remain the internal identifiers.
+
+### Transitions
+
+```ruby
+# Add an issue to the pipeline board
+item = PMS::ProjectItem.create!(issue, project_number: PMS::Pipeline.resolve_pipeline_project_number!)
+
+# Forward transitions
+PMS::Pipeline.take!(item)                   # Started
+PMS::Pipeline.mark_in_review!(item)         # In Review
+PMS::Pipeline.request_testing!(item)        # flips Testing single-select to active
+PMS::Pipeline.mark_ready_for_release!(item) # Ready for Release
+
+# Deployment-driven transitions
+PMS::Pipeline.start_deployment!(commit_sha: 'abc123…')  # every Ready item whose issue is in the commit -> Release in Progress
+PMS::Pipeline.complete_deployment!(item, deployment_id: 42)  # Completed (when issue.metadata.auto_complete)
+
+# Remove from pipeline (deletes the project item)
+PMS::Pipeline.remove!(item)
+```
+
+Forward transitions call `Pipeline.guard_approvals!(issue)`, which raises `PMS::PendingApprovalsError` if the linked issue has un-approved required approvers. Batch/automated transitions (`start_deployment!`, `complete_deployment!`, `remove!`) skip the guard on purpose.
+
+### Webhook-driven automation
+
+The engine mounts two webhook endpoints when the pipeline is enabled:
+
+- `POST /webhooks/github` — takes GitHub `pull_request` events. On `closed` against a tracked branch, the gem calls `IssueLinker` to extract `#123` references from the PR body and commit messages, then transitions each linked issue (e.g. merged to main -> `start_deployment!`).
+- `POST /webhooks/aws` — takes CodeDeploy/SNS lifecycle events. On a successful deployment, the gem flips matching items to `Completed`.
+
+On a successful AWS deployment the gem completes each matching item individually (one
+`pipeline_completed.plan_my_stuff` event apiece), then fires a single
+`pipeline_deployment_completed.plan_my_stuff` batch event carrying every item that actually transitioned
+(payload: `:project_items`, `:issue_numbers`, `:commit_sha`). It is skipped when nothing transitioned, so subscribers
+(release-notes mailer, Slack summary, changelog generator) get one clean "deployment finished" signal
+without debouncing the per-item events.
+
+See `designs/release_cycle/plan.md` for the full design, including the `projects_v2_item` path that fires
+`Pipeline.take!` when a human drags an item to Started on github.com.
+
+### "Take" button
+
+The mounted UI exposes a **Take** button on pipeline issues that calls `Pipeline.take!` and assigns the current user. Your app's user-id -> GitHub login mapping is provided by `config.github_login_for` (a hash keyed by user id).
 
 ## Verify setup
 
@@ -239,7 +737,7 @@ The gem provides test helpers for consuming apps:
 require 'plan_my_stuff/test_helpers'
 
 RSpec.configure do |config|
-  config.include PlanMyStuff::TestHelpers
+  config.include PMS::TestHelpers
 end
 ```
 
@@ -259,26 +757,52 @@ expect_pms_item_moved(status: 'In Review')
 
 ## Engine routes
 
-The engine provides these routes (all under the configured mount point):
+All routes are under the engine's mount point. Each group can be disabled via `config.mount_groups = { issues: true, projects: true, webhooks: true }`; pipeline-only routes (`/issues/:id/take`, `/webhooks/*`) are also gated on `config.pipeline_enabled`. See `config/routes.rb` for the source of truth.
+
+### Issues
 
 | Route | Action |
 |---|---|
-| `GET /` | Issue index |
-| `GET /issues/new` | New issue form |
-| `POST /issues` | Create issue |
-| `GET /issues/:id` | Issue detail with comments |
-| `GET /issues/:id/edit` | Edit issue form |
-| `PATCH /issues/:id` | Update issue |
-| `PATCH /issues/:id/close` | Close issue |
-| `PATCH /issues/:id/reopen` | Reopen issue |
-| `POST /issues/:id/comments` | Create comment |
-| `GET /issues/:id/comments/:id/edit` | Edit comment |
-| `PATCH /issues/:id/comments/:id` | Update comment |
-| `POST /issues/:id/labels` | Add label |
-| `DELETE /issues/:id/labels/:name` | Remove label |
-| `GET /projects` | Project list |
-| `GET /projects/:id` | Project board |
-| `POST /projects/:id/items` | Add item to project |
-| `PATCH /projects/:id/items/:id/move` | Move item |
-| `PATCH /projects/:id/items/:id/assign` | Assign item |
+| `GET /issues`, `GET /issues/new`, `POST /issues` | index, new, create |
+| `GET /issues/:id`, `GET /issues/:id/edit`, `PATCH /issues/:id` | show, edit, update |
+| `POST /issues/:issue_id/closure` / `DELETE …/closure` | close / reopen |
+| `POST /issues/:issue_id/waiting` / `DELETE …/waiting` | mark / clear waiting-on-user |
+| `POST /issues/:issue_id/viewers` / `DELETE …/viewers/:id` | add / remove viewer |
+| `POST /issues/:issue_id/take` (pipeline) | Take button -> `Pipeline.take!` |
+| `POST /issues/:issue_id/comments`, `GET …/comments/:id/edit`, `PATCH …/comments/:id` | create / edit / update comment |
+| `POST /issues/:issue_id/labels` / `DELETE …/labels/:id` | add / remove label |
+| `POST /issues/:issue_id/links` / `DELETE …/links/:id` | link / unlink related issue |
+| `POST /issues/:issue_id/approvals`, `PATCH …/approvals/:id`, `DELETE …/approvals/:id` | request / grant or revoke / remove approver |
+
+### Projects
+
+| Route | Action |
+|---|---|
+| `GET /projects`, `GET /projects/new`, `POST /projects` | index, new, create |
+| `GET /projects/:id`, `GET /projects/:id/edit`, `PATCH /projects/:id` | show, edit, update |
+| `POST /projects/:project_id/items` | add item |
+| `PATCH /projects/:project_id/items/:item_id/status` | move item to a status column |
+| `PATCH /projects/:project_id/items/:item_id/assignment` / `DELETE …/assignment` | assign / unassign |
+
+### Testing projects
+
+| Route | Action |
+|---|---|
+| `GET /testing_projects/new`, `POST /testing_projects` | new, create |
+| `GET /testing_projects/:id`, `GET …/:id/edit`, `PATCH …/:id` | show, edit, update |
+| `GET /testing_projects/:testing_project_id/items/new`, `POST …/items` | new, create item |
+| `PATCH /testing_projects/:testing_project_id/items/:item_id/status` | move item |
+| `GET …/items/:item_id/result/new`, `POST …/items/:item_id/result` | record pass/fail result |
+
+### Webhooks (pipeline only)
+
+| Route | Action |
+|---|---|
+| `POST /webhooks/github` | GitHub PR / projects_v2_item events |
+| `POST /webhooks/aws` | AWS CodeDeploy / SNS lifecycle events |
+
+## Controller overrides
+
+See [CONFIGURATION.md](CONFIGURATION.md#controller-overrides) for the full walkthrough including subclassing,
+per-route registration, and the per-action block hook.