agris 0.18.0 → 1.0.0

data/.claude/commands/spec.md

@@ -0,0 +1,172 @@
+# /spec
+
+Generate and maintain implementation-ready specs from Jira work items or developer descriptions.
+
+**Agent:** `~/.config/claude-playbook/global/agents/spec.md`
+
+## Mode Detection
+
+**Pull mode (default):** Ask ONE question at a time with numbered options. Never ask two questions in one message.
+
+**Push mode:** If `$ARGUMENTS` contains `--push`, or if both `issue` AND `spec` arguments are provided, skip questions and execute directly using the full protocol below.
+
+## Arguments
+| Key | Required | Description | Example |
+|-----|----------|-------------|---------|
+| issue | No | Jira issue key to generate spec from | `issue=PROJ-42` |
+| spec | No | Path to existing spec to update | `spec=docs/specs/SPEC-003-auth.md` |
+| --push | No | Skip pull prompting, execute directly | `--push` |
+
+---
+
+## Pull Prompting Flow
+
+### Step 1 — Intent
+
+If no arguments or only partial arguments are provided, start here:
+
+> **What would you like to do?**
+>
+> 1. Generate a spec from a Jira issue (epic/story/subtask)
+> 2. Update an existing spec with changes from Jira
+> 3. Generate a spec from scratch (no Jira issue)
+> 4. Review/audit an existing spec
+
+Wait for the user's answer before proceeding.
+
+### Step 2 — Source Material
+
+Based on the answer, ask ONE follow-up:
+
+- **If option 1:** "What is the Jira issue key? (e.g., PROJ-42)"
+  Then execute the Jira Hierarchy Crawl: fetch the issue, crawl upward (subtask → story → epic), follow `blocks`/`is blocked by` links, pull sibling names if context is thin, search Confluence for related BRDs/PRDs. Summarize what you found. Ask: "Does this capture the scope? (1) Yes, proceed (2) No, let me clarify"
+- **If option 2:** "Which spec?" List existing specs in `docs/specs/` as numbered options.
+  Then fetch current Jira state for linked issues and diff against the spec.
+- **If option 3:** "Describe the feature in 1-2 sentences. Who is the user and what problem does it solve?"
+- **If option 4:** "Which spec?" List existing specs as numbered options.
+
+### Step 3 — Scope Confirmation
+
+After gathering source material, present a scope proposal:
+
+> **Based on what I found, I think the spec should cover:**
+> - Feature: {name}
+> - Scope level: {epic / story / subset}
+> - In scope: {1-3 bullet summary}
+> - Out of scope: {what this does NOT cover}
+> - Related specs: {any existing specs that overlap}
+>
+> **Does this scope look right?**
+> 1. Yes, write the spec
+> 2. Add something
+> 3. Remove something
+> 4. Start over
+
+### Step 4 — Infrastructure Check
+
+If the scope includes Docker, Terraform, CI/CD, or deployment:
+
+> **This feature includes infrastructure components. Recommendation:**
+> 1. Split into separate app spec + infra spec (recommended)
+> 2. Keep as one spec
+> 3. Spec only the app portion, flag infra for DevOps
+
+### Step 5 — Execute
+
+Proceed to the Protocol below.
+
+---
+
+## Protocol
+
+### Standards — Read When Relevant
+
+Read these files when your spec work touches each area:
+
+| When writing about | Read this file |
+|-------------------|---------------|
+| Naming conventions | `~/.config/claude-playbook/global/standards/practices/naming.md` |
+| Spec format | `~/.config/claude-playbook/global/templates/ai/spec-writing-guide.md` (scaffolded to `.claude/ai/` in projects) |
+| Architecture or layering | `~/.config/claude-playbook/global/standards/practices/architecture.md` |
+| Testing strategy | `~/.config/claude-playbook/global/standards/practices/testing.md` |
+
+### Jira Hierarchy Crawl
+
+When generating from a Jira issue:
+1. Fetch the given issue.
+2. Crawl upward: subtask → parent story → parent epic (as far as the chain goes).
+3. Follow `blocks` and `is blocked by` links (not `relates to`).
+4. If story/epic description is thin, pull sibling names and summaries for scope context.
+5. Search Confluence for BRDs/PRDs linked from the epic or matching keywords.
+
+### Existing Spec Check
+
+Before writing any spec:
+1. Scan `docs/specs/` for specs referencing the same Jira issue keys, epic, or feature area.
+2. If a matching spec exists: switch to update flow.
+3. If related specs exist: present to developer for cross-referencing.
+
+### Spec Authoring
+
+1. **Read the spec template** at `~/.config/claude-playbook/global/templates/specs/spec-template.md` — do not rely on memory.
+2. Scan `docs/specs/` for existing specs. Determine next SPEC ID number.
+3. Write the spec in `docs/specs/SPEC-{###}-{kebab-title}.md`.
+4. Include: numbered rules (R#), acceptance criteria (AC-#), acceptance tests (AT#) in Given/When/Then, edge cases (E#).
+5. Every AT must include `Covers: R#` references.
+6. Include all sections that apply, omit sections that genuinely don't (no "N/A" filler).
+7. Keep spec under 500 lines. If larger, propose decomposition.
+8. Present draft to developer for approval before writing to disk.
+
+### Task Breakdown
+
+1. Propose tasks from spec ACs, sized for small PRs (1-3 points).
+2. Estimate Fibonacci complexity per task (1, 2, 3, 5, 8, 13). These are preliminary — PM may adjust.
+3. Split tasks >= 5 points or document rationale for keeping whole.
+4. Output tasks in Jira-ready format (operational mode) or track in spec (GitHub-only mode).
+5. Verify all ACs are covered by at least one proposed task.
+
+The spec agent does NOT create Jira issues. The PM or developer creates them from the proposed breakdown.
+
+---
+
+## Self-Test Checklist
+
+Before handoff, verify ALL of these. Output the checklist with pass/fail:
+
+```
+SELF-TEST
+- [ ] Every rule has a unique R# ID
+- [ ] Every AC has a unique AC-# ID
+- [ ] Every AT has a unique AT# ID and Covers: R# reference
+- [ ] No ambiguous language (should probably, generally, maybe)
+- [ ] No duplicate IDs
+- [ ] Every R# is covered by at least one AT#
+- [ ] Every AC is mapped to at least one proposed task
+- [ ] Tasks >= 5 points have split review or documented rationale
+- [ ] Out-of-scope section is explicit
+- [ ] Cross-referenced specs listed in Dependencies
+Standards consulted: [{list of practice files actually read}]
+```
+
+## Handoff (MANDATORY)
+
+Output a SPEC_TO_DEV handoff summary:
+- Spec path and SPEC ID
+- Proposed task list with AC mappings and complexity estimates
+- Risks and dependencies
+- State: "Spec ready for development — see {spec path}. Proposed tasks ready for Jira creation."
+
+Do NOT assume a developer will automatically pick up the work.
+
+## Hard Rules
+- **NEVER write, edit, or create application code.** You may only write to `docs/specs/` and handoff files. Implementation is the developer's job.
+- **NEVER write to Jira.** Read-only access. Propose tasks; human or PM creates them.
+- **NEVER write to Confluence.** Read-only access for context gathering.
+- Do not add unapproved scope.
+- Do not leave ambiguous criteria or missing AC IDs.
+- Do not allow tasks >= 5 points without documented split review.
+- Do not write specs without developer approval of scope first.
+- NEVER merge PRs. Only human users merge.
+- If blocked >30 minutes, create blocker report.
+
+$ARGUMENTS

data/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  # Split from lint deliberately: a spec failure and a lint failure are
+  # different problems, and each reports its own status check. Specs run
+  # across a Ruby matrix; lint does not — rubocop's output does not vary
+  # by Ruby, so one run on the floor is enough.
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        # Floor, current, next, and 4.0 — which a consuming application
+        # already runs. The floor must stay green for the gemspec's
+        # required_ruby_version to mean anything.
+        ruby: ['3.1', '3.3', '3.4', '4.0']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run specs
+        run: |
+          bundle exec rspec \
+            --format progress \
+            --format RspecJunitFormatter \
+            --out tmp/test-results/rspec.xml
+
+      # upload-artifact@v4 rejects duplicate names, so each matrix leg
+      # needs its own.
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: ${{ !cancelled() }}
+        with:
+          name: test-results-ruby-${{ matrix.ruby }}
+          path: tmp/test-results/
+
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version-file: .ruby-version
+          bundler-cache: true
+
+      - name: Run rubocop
+        run: bundle exec rubocop

data/.gitignore

@@ -12,3 +12,8 @@
 .rspec_status
 .DS_Store
 /vendor
+
+# Claude Playbook (auto-added)
+.claude/state/
+.claude/settings.local.json
+.claude/agent-memory-local/

data/.rubocop.yml

@@ -1,23 +1,14 @@
 inherit_from: .rubocop_todo.yml
 
-Rails:
-  Enabled: false
 AllCops:
-  TargetRubyVersion: 2.4
+  TargetRubyVersion: 3.1
   Exclude:
     - "vendor/**/*"
     - "db/schema.rb"
     - "node_modules/**/*"
     - bin/*
   UseCache: false
-Layout/DotPosition:
-  Description: Checks the position of the dot in multi-line method calls.
-  StyleGuide: https://github.com/bbatsov/ruby-style-guide#consistent-multi-line-chains
-  Enabled: true
-  EnforcedStyle: trailing
-  SupportedStyles:
-  - leading
-  - trailing
+  SuggestExtensions: false
 Layout/EmptyLineAfterMagicComment:
   Description: 'Add an empty line after magic comments to separate them from code.'
   StyleGuide: '#separate-magic-comments-from-code'
@@ -66,16 +57,9 @@ Style/PercentLiteralDelimiters:
     "%w": "()"
     "%W": "()"
     "%x": "()"
-Naming/PredicateName:
+Naming/PredicatePrefix:
   Description: Check the names of predicate methods.
-  StyleGuide: https://github.com/bbatsov/ruby-style-guide#bool-methods-qmark
   Enabled: true
-  NamePrefix:
-  - is_
-  - has_
-  - have_
-  NamePrefixBlacklist:
-  - is_
   Exclude:
   - spec/**/*
 Style/RaiseArgs:
@@ -241,7 +225,7 @@ Style/WhenThen:
 Lint/EachWithObjectArgument:
   Description: Check for immutable argument given to each_with_object.
   Enabled: true
-Lint/HandleExceptions:
+Lint/SuppressedException:
   Description: Don't suppress exception.
   StyleGuide: https://github.com/bbatsov/ruby-style-guide#dont-hide-exceptions
   Enabled: false
@@ -252,82 +236,6 @@ Lint/LiteralInInterpolation:
   Description: Checks for literals used in interpolation.
   Enabled: false
 
-##################### Rails ##################################
-
-Rails/ActionFilter:
-  Description: 'Enforces consistent use of action filter methods.'
-  Enabled: true
-Rails/Date:
-  Description: >-
-                  Checks the correct usage of date aware methods,
-                  such as Date.today, Date.current etc.
-  Enabled: true
-Rails/Delegate:
-  Description: 'Prefer delegate method for delegations.'
-  Enabled: true
-Rails/Exit:
-  Description: >-
-                  Favor `fail`, `break`, `return`, etc. over `exit` in
-                  application or library code outside of Rake files to avoid
-                  exits during unit testing or running in production.
-  Enabled: true
-Rails/FindBy:
-  Description: 'Prefer find_by over where.first.'
-  StyleGuide: 'https://github.com/bbatsov/rails-style-guide#find_by'
-  Enabled: true
-Rails/FindEach:
-  Description: 'Prefer all.find_each over all.find.'
-  StyleGuide: 'https://github.com/bbatsov/rails-style-guide#find-each'
-  Enabled: true
-Rails/HasAndBelongsToMany:
-  Description: 'Prefer has_many :through to has_and_belongs_to_many.'
-  StyleGuide: 'https://github.com/bbatsov/rails-style-guide#has-many-through'
-  Enabled: true
-Rails/HttpPositionalArguments:
-  Description: 'Rails 5 only, disabled to keep Hound quiet'
-  Enabled: false
-Rails/NotNullColumn:
-  Description: 'Do not add a NOT NULL column without a default value'
-  Enabled: false
-Rails/Output:
-  Description: 'Checks for calls to puts, print, etc.'
-  Enabled: true
-Rails/OutputSafety:
-  Description: 'The use of `html_safe` or `raw` may be a security risk.'
-  Enabled: true
-Rails/PluralizationGrammar:
-  Description: 'Checks for incorrect grammar when using methods like `3.day.ago`.'
-  Enabled: true
-Rails/ReadWriteAttribute:
-  Description: >-
-                 Checks for read_attribute(:attr) and
-                 write_attribute(:attr, val).
-  StyleGuide: 'https://github.com/bbatsov/rails-style-guide#read-attribute'
-  Enabled: true
-Rails/RequestReferer:
-  Description: 'Use consistent syntax for request.referer.'
-  Enabled: true
-Rails/SafeNavigation:
-  Description: "Use Ruby's safe navigation operator (`&.`) instead of `try!`"
-  Enabled: true
-Rails/ScopeArgs:
-  Description: 'Checks the arguments of ActiveRecord scopes.'
-  Enabled: true
-Rails/TimeZone:
-  Description: 'Checks the correct usage of time zone aware methods.'
-  StyleGuide: 'https://github.com/bbatsov/rails-style-guide#time'
-  Reference: 'http://danilenko.org/2012/7/6/rails_timezones'
-  Enabled: true
-Rails/UniqBeforePluck:
-  Description: 'Prefer the use of uniq or distinct before pluck.'
-  Enabled: true
-Rails/Validation:
-  Description: 'Use validates :attribute, hash of validations.'
-  Enabled: true
-Security/JSONLoad:
-  Description : 'Prefer usage of JSON.parse'
-  Enabled: true
-
 Layout/DotPosition:
   Description: Checks the position of the dot in multi-line method calls.
   StyleGuide: https://github.com/bbatsov/ruby-style-guide#consistent-multi-line-chains
@@ -354,11 +262,10 @@ Style/ClassAndModuleChildren:
   - nested
 Style/MultilineIfModifier:
   Enabled: false
-Style/StringLiterals:
-  Description: Checks if uses of quotes match the configured preference.
-  StyleGuide: https://github.com/bbatsov/ruby-style-guide#consistent-string-literals
+Naming/VariableNumber:
+  Description: >-
+    The codebase consistently uses trailing _1 / _2 to enumerate records,
+    mostly in spec `let` names. Match that rather than renaming for the
+    sake of the cop's default.
   Enabled: true
-  EnforcedStyle: single_quotes
-  SupportedStyles:
-  - single_quotes
-  - double_quotes
+  EnforcedStyle: snake_case

data/.ruby-version

@@ -0,0 +1 @@
+3.1

data/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Ruby support is expressed through `required_ruby_version` rather than the
+version number — see [docs/RELEASING.md](docs/RELEASING.md). Raising that floor
+is a breaking change and takes a major bump; adding support for a newer Ruby
+takes none.
+
+## [1.0.0] - 2026-09-14
+
+First release since `v0.19.0`. The `1.0.0` bump declares the public API stable
+and makes semver's major-bump signal available, which `0.x` does not.
+
+### Added
+
+- `Api::AccountsReceivables::Payments`, adding `#create_payment`,
+  `#apply_payment` and `#post_payment` to the client, with the `NewPayment`,
+  `NewPaymentRemark` and `PaymentPostResult` XML models. (#44)
+- `Api::AccountsPayables::Disbursements`, adding `#create_disbursement` to the
+  client, with the `NewDisbursement` XML model. (#40)
+- `freight_uom` declared on `Api::Grain::NewTicket`. (#43)
+
+### Changed
+
+- **Ruby 3.1 or newer is now required.** The gemspec declares
+  `required_ruby_version >= 3.1`; previously it declared no floor at all, so
+  the gem could be installed on unsupported Rubies and fail at runtime.
+  Applications below 3.1 will resolve to `v0.19.0` and should stay there. (#52)
+- **`*_changed_since` methods now take `detail:` as a keyword argument**
+  rather than a positional boolean. Calls such as
+  `client.orders_changed_since(time, true)` must become
+  `client.orders_changed_since(time, detail: true)`. Affects
+  `invoices_changed_since`, `purchase_contracts_changed_since`,
+  `sales_contracts_changed_since`, `delivery_tickets_changed_since` and
+  `orders_changed_since`. (#57)
+- Versioning moved to a single line. An earlier scheme encoded the supported
+  Ruby in the version number (`0.19.x` for Ruby 3.1, `0.2x` for Ruby 3.3);
+  it fought semver and RubyGems has no concept of release lines, always serving
+  the highest version as `latest`. `0.20.0` and `0.21.0` were never published
+  and are superseded by this release. (#52)
+
+### Fixed
+
+- `Api::PostResult#rejections` no longer raises when a post is processed
+  cleanly. A processed post reports an empty `<reject />`, which previously
+  produced a `NoMethodError` rather than an empty list. (#44)
+- `bundle exec rake` runs to completion again. RuboCop had been unable to run
+  at all since the move to Ruby 3.x — it calls the positional
+  `Psych.safe_load` signature removed in Psych 4, and rejected any 3.x value in
+  `.ruby-version`. Separately, lint offences had accumulated since February
+  2024 because nothing was running the linter. (#52)
+
+### Internal
+
+- CI migrated from CircleCI to GitHub Actions, running specs and lint as
+  separate jobs so each reports its own status. CircleCI ran specs only, which
+  is why the RuboCop breakage went unnoticed across three releases' worth of
+  commits. (#52)
+- Specs now run against Ruby 3.1, 3.3 and 3.4, so `required_ruby_version` is
+  verified rather than asserted. (#53)
+- Release process documented in [docs/RELEASING.md](docs/RELEASING.md). (#54)
+- RuboCop bumped from 0.54.0 to 1.x, retiring four workarounds that existed
+  only to keep a 2018 release running on Ruby 3.x — a `psych` pin and three
+  disabled or duplicated configuration entries. Ruby 4.0 added to the CI
+  matrix, which a consuming application already runs. (#57)
+
+---
+
+## Earlier releases
+
+Releases up to and including `v0.19.0` predate this changelog. See the
+[commit history](https://github.com/westernmilling/agris.rb/commits/master)
+and [release tags](https://github.com/westernmilling/agris.rb/tags).
+
+[1.0.0]: https://github.com/westernmilling/agris.rb/compare/v0.19.0...v1.0.0

data/CLAUDE.md

@@ -0,0 +1,98 @@
+# CLAUDE.md — Project Configuration
+
+## Product Context
+- **Product name:** agris (Ruby gem)
+- **Primary user/persona:** Ruby application developers at Western Milling (and downstream consumers) who integrate with the Agris ERP Web Services SOAP API.
+- **Problem statement:** Agris exposes its ERP data (grain contracts/tickets, inventory orders, delivery tickets, AR invoices, AP vouchers, commodity codes, document tracking) through a single SOAP `ProcessMessage` endpoint. This gem wraps that endpoint with a typed Ruby client so consumers don't construct/parse XML by hand.
+- **Non-goals:**
+  - Not a Rails engine — pure library, no UI or persistence.
+  - Not a generic SOAP client — only models the Agris message catalog.
+  - Does not host or proxy Agris itself; callers supply their own endpoint, dataset, and credentials.
+
+## Stack and Dependencies
+- **Languages/frameworks:** Ruby 3.1 (`.ruby-version`, which CI also reads). Rubocop still lints against `TargetRubyVersion: 2.4`.
+- **Key applications/packages:**
+  - Runtime: `savon ~> 2.11` (SOAP client).
+  - Dev/test: `rspec ~> 3.0`, `rspec_junit_formatter ~> 0.4.1`, `webmock ~> 2.3`, `simplecov 0.17`, `rubocop 0.54.0`, `pry-byebug`, `rake ~> 12.3.3`, `bundler ~> 2.3.7`.
+- **Data layer:** None local. Remote system of record is the Agris ERP database, accessed via its SOAP `ProcessMessage` endpoint (see `lib/agris/savon_request.rb` and `lib/agris/process_message_response.rb`).
+- **Build command:** `bundle install` (or `bin/setup`).
+- **Test command:** `bundle exec rspec` (or `bundle exec rake spec`).
+- **Lint command:** `bundle exec rubocop`.
+- **Dev server command:** N/A (library). For interactive exploration: `bin/console` (boots IRB with the gem loaded).
+
+## Verification Commands
+- **Run tests:** `bundle exec rspec`
+- **Run linter:** `bundle exec rubocop`
+- **Type check:** N/A (no Sorbet/RBS in this project)
+- **Run everything (default rake):** `bundle exec rake` — runs `spec` then `rubocop`.
+
+## Domain Glossary
+Define key business terms unique to this project so agents use correct terminology.
+
+| Term | Definition |
+|------|-----------|
+| Agris | Third-party agribusiness ERP. All API messages target this system. |
+| Dataset | Agris tenancy/company identifier (e.g., `'001'`). Required as a keyword arg on every `Agris::Client.new`; scopes all requests. |
+| Context | `Agris::Context` — endpoint config bundle: base URL, default dataset, dataset path, database name, user, password. |
+| Credentials | `Agris::Credentials::Anonymous` or `Agris::Credentials::BasicAuth` — auth strategy passed to the underlying request. |
+| ProcessMessage | The single SOAP operation Agris exposes; every API call serializes a typed request XML and parses a typed response XML through it. |
+| Request type | Pluggable transport (`Agris::SavonRequest`). Selected via `Agris.request_type`. |
+| XmlModel | `Agris::XmlModel` — base class for declarative request/response XML payloads used across `lib/agris/api/**`. |
+| Grain module | `Agris::Api::Grain::*` — tickets, contracts (purchase/sales), commodity codes, grade factors, rates. |
+| Inventory module | `Agris::Api::Inventory::*` — delivery tickets and orders. |
+| Voucher / Invoice | AP voucher (`Api::AccountsPayables`) and AR invoice (`Api::AccountsReceivables`) postings. |
+| Messages module | `Api::Messages::*` — document-tracking and "changed since" queries (invoices, sales contracts, delivery tickets, orders, commodity-code documents). |
+
+## Local Development Setup
+- **Prerequisites:** Ruby 3.1.x and Bundler 2.3+. CI reads `.ruby-version`, so local dev and CI cannot drift; other Ruby versions may work but are unverified.
+- **Install steps:**
+  1. `git clone git@github.com:westernmilling/agris.rb.git`
+  2. `cd agris.rb`
+  3. `bin/setup` (runs `bundle install`)
+- **How to run locally:** This is a library — no server. Use `bin/console` to load the gem in IRB and exercise the client interactively.
+- **How to seed data:** N/A. Tests use fixture XML under `spec/fixtures/agris/**` (stubbed via WebMock); they do not require a live Agris endpoint.
+- **How to run tests:** `bundle exec rspec` (full suite), `bundle exec rspec spec/lib/agris/client/grain/purchase_contracts_spec.rb` (one file), or `bundle exec rake` (specs + rubocop).
+- **Key URLs:**
+  - Repo: https://github.com/westernmilling/agris.rb
+  - CI: GitHub Actions (workflow at `.github/workflows/ci.yml`).
+  - Coverage / quality: Code Climate (badges in `README.md`; config in `.codeclimate.yml`).
+
+## Common Gotchas
+- **Ruby 2.4 target.** Rubocop's `TargetRubyVersion` is `2.4`. Avoid syntax/stdlib introduced after 2.4 unless you are intentionally bumping the floor.
+- **Rubocop 0.54.0 is pinned and old.** Many newer cops do not exist; `.rubocop_todo.yml` carries existing exemptions. Don't auto-correct broadly without running the full suite afterward.
+- **`Agris::HTTPartyRequest` is autoloaded but the file is not present** in `lib/agris/`. Only `SavonRequest` is implemented — configure `Agris.request_type = Agris::SavonRequest`. The dangling autoload is a known wart.
+- **`dataset:` is keyword-required on `Client.new`.** `Agris::Client.new(dataset: '001')` — forgetting the keyword raises `ArgumentError`.
+- **All requests funnel through Agris's single `ProcessMessage` SOAP op.** Errors come back in-band as `<MessageStatus>` payloads (see `lib/agris/process_message_response.rb`), not as HTTP errors. Inspect `ApiError` / `MessageError` / `SystemError` / `UnknownError` raised from the client.
+- **Fixtures are XML, sometimes paired with JSON snapshots.** When adding a new endpoint, add both request and response fixtures under `spec/fixtures/agris/<area>/`.
+- **`lib/hash.rb` monkey-patches core `Hash`.** Be careful when refactoring helpers — they may be in use across XML models.
+- **Released to RubyGems as `agris`.** Bumping `lib/agris/version.rb` and running `bundle exec rake release` will tag, push, and publish. Do not run `rake release` casually.
+
+## Integrations
+- **Jira project key:** _Not configured for this repo._ <!-- Fill in if/when this gem is tracked in Jira; used for branch naming and issue linking. -->
+- **Staging URL:** N/A (library, no deployed environment).
+- **CI pipeline:** GitHub Actions — `.github/workflows/ci.yml`. Two parallel jobs on pushes to `master` and on every pull request: `test` (`bundle exec rspec`, JUnit output uploaded as an artifact) and `lint` (`bundle exec rubocop`). They report separate status checks so a spec failure and a lint failure are distinguishable at a glance.
+
+## Project Overrides
+Rules here override global CLAUDE.md rules for this project.
+
+### Architecture Rules
+- **Layering rules:**
+  - `lib/agris.rb` — module-level configuration (`Agris.configure`) and autoloads.
+  - `lib/agris/client.rb` — single entry point; mixes in API modules from `lib/agris/api/**`.
+  - `lib/agris/api/<area>/<resource>.rb` — one Ruby module per Agris message; defines request building and response parsing using `XmlModel`.
+  - `lib/agris/{savon_request,process_message_response,context,credentials,...}.rb` — transport, response envelope, config primitives.
+  - Add new endpoints by creating a module under the appropriate `api/<area>/` namespace and including it in `Client`.
+- **Dependency boundaries:**
+  - API modules must not call `Savon` directly — go through the configured `request_type`.
+  - Keep XML construction inside `XmlModel` subclasses, not inline in client methods.
+  - No Rails / ActiveSupport assumptions — this is a plain Ruby gem.
+- **Error-handling conventions:**
+  - Surface Agris failures as one of the existing `Agris::*Error` classes defined in `lib/agris.rb`. Don't introduce new error hierarchies without discussion.
+  - Don't rescue and swallow inside API modules; let the caller decide.
+
+### Delivery Rules
+- **Branch strategy:** Trunk-based off `master`. Feature branches per change; PRs target `master`.
+- **PR size policy:** ~200 LOC per PR, one testable behavior. RSpec coverage required for behavior changes; map specs to acceptance criteria when specs exist under `docs/specs/`.
+
+### Model Overrides
+_None._

data/README.md

@@ -52,7 +52,15 @@ Enjoy!
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. For releases, see [Releasing](#releasing) below.
+
+## Releasing
+
+The gem is published to RubyGems as `agris`, on a single version line from
+`master`. Ruby support is expressed through `required_ruby_version` rather than
+the version number, and `rake release` tags, pushes and publishes in one
+irreversible step — see [docs/RELEASING.md](docs/RELEASING.md) before cutting a
+release.
 
 ## Contributing
 

data/agris.gemspec

@@ -12,6 +12,7 @@ Gem::Specification.new do |spec|
   spec.summary = 'Ruby client library for Agris API'
   spec.homepage = 'https://github.com/westernmilling/agris.rb'
   spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.1'
 
   spec.files = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
@@ -22,12 +23,12 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'savon', '~> 2.11'
 
-  spec.add_development_dependency 'bundler', '~> 2.3.7'
+  spec.add_development_dependency 'bundler', '>= 2.3'
   spec.add_development_dependency 'pry-byebug'
   spec.add_development_dependency 'rake', '~> 12.3.3'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rspec_junit_formatter', '~> 0.4.1'
-  spec.add_development_dependency 'rubocop', '0.54.0'
+  spec.add_development_dependency 'rubocop', '~> 1.80'
   spec.add_development_dependency 'simplecov', '0.17'
   spec.add_development_dependency 'webmock', '~> 2.3'
 end