Exclude cancelled orders from bulk co-op reports

AGENTS.md

@@ -0,0 +1,162 @@
+# AGENTS.md — Open Food Network
+
+> **Status**: v0.3 — field-tested on Ubuntu 24.04, March 2026; process docs added May 2026
+> Maintained in [GOAT Agent Files](https://gitlab.com/our-sci/goat-agent-files). Improvements via MR.
+
+<!-- Keep this file under 200 lines. See CONTRIBUTING.md before making changes. -->
+
+## OFN official process docs (read & follow these)
+
+OFN has its own contributor documentation. This file gives you project conventions and
+pitfalls; it does **not** replace OFN's process. Read and follow OFN's own guides — when they
+disagree with this file, OFN's docs win. The full forum → issue → PR → merge walkthrough is in
+[`contributing-workflow.md`](goat-agents/contributing-workflow.md). Core sources:
+
+- [`CONTRIBUTING.md`](https://github.com/openfoodfoundation/openfoodnetwork/blob/master/CONTRIBUTING.md) and [`GETTING_STARTED.md`](https://github.com/openfoodfoundation/openfoodnetwork/blob/master/GETTING_STARTED.md) — fork/`upstream`, issue-numbered branch, TDD
+- Wiki: [Making a great pull request](https://github.com/openfoodfoundation/openfoodnetwork/wiki/Making-a-great-pull-request), [Making a great commit](https://github.com/openfoodfoundation/openfoodnetwork/wiki/Making-a-great-commit), [Code Conventions](https://github.com/openfoodfoundation/openfoodnetwork/wiki/Code-Conventions), [Testing & Rspec Tips](https://github.com/openfoodfoundation/openfoodnetwork/wiki/Testing-and-Rspec-Tips)
+- Wiki: [Review, test, merge & deploy](https://github.com/openfoodfoundation/openfoodnetwork/wiki/The-process-of-review%2C-test%2C-merge-and-deploy) — a PR needs **2 core reviewers** + a staging test stage before merge; releases are ~weekly. Don't expect an instant merge.
+- **Discuss features first on the [community forum](https://community.openfoodnetwork.org)** ([Product Development backlog](https://community.openfoodnetwork.org/c/product-dev/5)); check the [user guide](https://guide.openfoodnetwork.org/) in case the feature already exists.
+- **Write issues** with the right [template](https://github.com/openfoodfoundation/openfoodnetwork/tree/master/.github/ISSUE_TEMPLATE) (bug / story / feature / tech-debt) and a [bug-severity](https://github.com/openfoodfoundation/openfoodnetwork/wiki/Bug-severity) label.
+- Be civil and patient per the [Code of Conduct](https://github.com/openfoodfoundation/openfoodnetwork/blob/master/CODE_OF_CONDUCT.md) — reviewers and testers are volunteers.
+
+## Setup
+
+OFN uses native Ruby for local development. Docker exists but is too slow for active work
+(20+ second page loads vs ~1-3s natively).
+
+```bash
+# Clone
+git clone https://github.com/openfoodfoundation/openfoodnetwork.git
+cd openfoodnetwork
+
+# Install system deps (Ubuntu) — includes cmake, postgres, redis, imagemagick
+bash script/install-system-deps.sh   # requires sudo
+
+# Install Ruby via rbenv (compile ~5-10 min)
+rbenv install $(cat .ruby-version) && rbenv global $(cat .ruby-version)
+
+# Install Node via nodenv
+nodenv install $(cat .node-version) && nodenv global $(cat .node-version)
+
+# Run OFN's setup script (gems + db + seed data, ~15 min first time)
+./script/setup
+
+# Start dev server (Rails + webpack + sidekiq)
+bundle exec foreman start
+```
+
+App at http://localhost:3000 — login: `ofn@example.com` / `ofn123`
+
+Full runbook with troubleshooting: [`setup.md`](goat-agents/setup.md)
+
+## Running tests
+
+```bash
+# Single spec file
+bundle exec rspec spec/models/spree/order_spec.rb
+
+# By line number
+bundle exec rspec spec/models/spree/order_spec.rb:42
+
+# System specs (browser)
+bundle exec rspec spec/system/
+
+# Prepare test database (after schema changes)
+bundle exec rake db:test:prepare
+```
+
+## Conventions
+
+- OFN is Ruby on Rails. It was originally built around Spree (a commerce engine) but is actively moving away from it — treat Spree as legacy context, not the primary architecture
+- Models in `app/models/spree/` are OFN's own files, edited directly — not via decorators. The Spree gem is a dependency but OFN owns these model files.
+- JavaScript: AngularJS (CoffeeScript, legacy — being phased out) lives in `app/assets/javascripts/`. Modern JS uses Stimulus + Hotwire/Turbo + CableReady (StimulusReflex). CableReady is planned for removal (reliability issues) — Turbo Streams is the preferred replacement. Some edge cases (e.g., report downloads) still use CableReady + polling; the future ideal is SSE, but not yet prioritised. There is no Vue.js.
+- Stimulus controllers are in `app/webpacker/controllers/` (shared) and `app/components/*/` (component-scoped). Naming: `[name]_controller.js`.
+- Database migrations go in `db/migrate/` — never modify existing migration files
+- i18n: all user-facing strings use `I18n.t()` or Rails `t()` helper — never hardcode strings. Prefer lazy lookup (`t('.key')`) in views to avoid polluting the global namespace
+- API is standard Rails (`ActionController::API`) at `app/controllers/api/v0/` and `app/controllers/api/v1/`. A separate DFC API engine lives at `engines/dfc_provider/`. Not Grape.
+
+## Responding to PR feedback
+
+Not all reviewer feedback carries equal weight. Calibrate your response based on who is giving the guidance.
+
+**Core maintainers** (as of March 2026 — verify with `gh pr list --state closed --limit 30 --json mergedBy`):
+- `mkllnk` (Maikel) and `rioug` — primary maintainers, most active reviewers and mergers. Follow their guidance immediately; update GOAT and memory accordingly.
+- `dacook` — active maintainer. High weight.
+
+**For core maintainer feedback**: apply it, update rules, and post a follow-up comment showing exactly what changed (show, don't tell).
+
+**For other contributors**: be positive and polite, but think it through before acting. Does the suggestion align with codebase conventions? Does it conflict with what maintainers have said? If uncertain, respond with a question or explain your reasoning rather than silently agreeing and changing course.
+
+## Before starting work on an issue
+
+Re-read the issue immediately before writing any code, even if you planned it earlier. Check:
+
+1. **Is it already claimed?** Look for a linked PR, an "In Progress" label, or a comment like "I'm working on this". If someone else has started, stop and pick a different issue.
+2. **Is there an open PR?** Run `gh pr list -R openfoodfoundation/openfoodnetwork --search "closes #ISSUE_NUMBER"` or scan recent PRs. An open PR means the fix is already underway.
+3. **Has the issue changed?** Scope, acceptance criteria, or approach may have been updated since you last read it. Skim all comments — the last one often supersedes earlier discussion.
+4. **Is it still open?** If it was closed (merged fix or won't-fix), pick another issue.
+
+These checks take 30 seconds and prevent duplicating work that another contributor has already done.
+
+## Boundaries
+
+**Always**:
+- Run tests before opening a PR: `bundle exec rspec spec/path/to/changed_spec.rb`
+- Write or update specs for all changed behavior
+- Run `./bin/rails db:migrate` after pulling changes with new migrations
+- Use the PR template (`.github/PULL_REQUEST_TEMPLATE.md`) when opening PRs — fill in What/Why, What should we test, and the Changelog Category checkbox
+- Only modify `config/locales/en.yml` — other locale files are managed by Transifex and will be overwritten on the next release
+- **Confirm fixes in the browser** before considering work done (Playwright, Cypress, or manual): reproduce the bug, then show it fixed. Screenshots must go in the **PR description** (not committed to the repo). GitHub only allows image uploads via web UI drag-and-drop — save screenshots to a known local path and ask the human collaborator to paste them into the PR description.
+
+**Ask first**:
+- Changes to database schema or existing migrations
+- Modifications to Spree core behavior (the commerce engine)
+- Changes to the v0 API endpoints — there is no OFN mobile app, but v0 must remain stable for external consumers
+- Adding new Ruby gems
+
+**Never**:
+- Modify existing migration files — create a new migration instead
+- Edit files in `vendor/` or Spree gem source
+- Hardcode environment-specific configuration — use ENV variables
+- Merge directly to `master` — all changes go through PR with CI passing
+
+## Common pitfalls
+
+1. **Confusing Spree gem source with OFN's model files**: `app/models/spree/` contains OFN's own versions of these models — edit them directly. The actual Spree gem source is in the bundle cache, not in `app/`.
+2. **Running `foreman start` instead of `bundle exec foreman start`**: Ubuntu ships a system `ruby-foreman` that uses system Ruby and can't find `bundle` → Always use `bundle exec foreman start`
+3. **AngularJS vs Stimulus confusion**: Legacy admin JS is AngularJS (CoffeeScript in `app/assets/javascripts/`). New admin features use Stimulus + Turbo. There is no Vue.js in OFN — never has been.
+4. **Modifying existing migrations**: Breaks reproducibility for other contributors → Create a new migration with the required change
+5. **Missing i18n**: Hardcoded English strings break translations → Use `I18n.t('key')` and add the key to `config/locales/en.yml`
+6. **RSpec global constant namespace pollution**: Constants defined at the top level of spec files (e.g. `MY_CONST = ...`) are truly global and leak across the test suite. Define them as local variables (`my_const = ...`) inside the `it` or `shared_examples` block where they are actually used.
+7. **Run rubocop before pushing**: CI runs reviewdog which fails on style offenses. Catch them locally first: `bundle exec rubocop --only-recognized-file-types path/to/changed/file.rb`. Common issue: extra blank lines at block body end (`Layout/EmptyLinesAroundBlockBody`).
+8. **Separate commits for different kinds of changes**: If a PR touches two unrelated concerns (e.g., fixing form label accessibility AND replacing display-only `label_tag nil` with `span`), put them in separate commits with a message explaining the distinction. Maintainers flag bundled changes that require different reasoning to review.
+9. **No git history rewrites once a PR is under review**: Once a reviewer has left a comment on the PR, treat the branch as append-only until merge — no force-pushes, rebases, or amends. Rewriting detaches inline comments from the diff they referenced and makes the review thread harder for the next reviewer to follow. Push additive fixup commits instead; squash (if wanted) happens at merge time. Before any review starts, rebase/amend is fine.
+
+## Closing the loop
+
+Beyond *responding* to feedback (see "Responding to PR feedback" above), you commit to following each PR/issue through to merge, close, or explicit handoff. This applies whether the work was authored with Claude, Codex, Gemini, Copilot, an open-source model, or by hand — the maintainer is talking to you, not your tool.
+
+- **Watch what you open.** Subscribe to the GitHub PR (and the linked issue if separate). If your assistant supports a session-start activity check, wire it in so CI failures and review comments surface promptly.
+- **Respond within ~1 week** to reviewer comments, especially from core maintainers. OFN reviewers are volunteers; silence pushes them to close work or stop reviewing AI-assisted contributions altogether.
+- **CI failures are your responsibility.** If reviewdog flags style or the test suite fails, fix it before the maintainer has to ask.
+- **Don't open and forget.** If you can't continue, post a note in the PR and either hand off or close. Stale PRs taint the appearance of the broader AI-assisted contribution effort.
+
+## Further reading
+
+- [`contributing-workflow.md`](goat-agents/contributing-workflow.md) — full forum → issue → PR → review/test/merge/deploy walkthrough, with links to OFN's official docs
+- [`antipatterns.md`](goat-agents/antipatterns.md) — extended examples of common AI mistakes
+- [`setup.md`](goat-agents/setup.md) — full dev environment runbook
+- [`review-checklist.md`](goat-agents/review-checklist.md) — what OFN maintainers flag in PR review
+- [`benchmarks/README.md`](goat-agents/benchmarks/README.md) — how to validate changes to this file
+
+## User-facing documentation (core context for any agent)
+
+When evaluating whether an OFN idea is already addressed by existing features, or when explaining how something currently works, **always consult the user-facing documentation first**:
+
+- **OFN User Guide** — https://guide.openfoodnetwork.org/ — the canonical guide for hub managers, producers, and shoppers. Covers basic features, hub-management tips, marketing tips, quick-start guides, FAQs, and a glossary. This is where to look when a proposed "feature" might already exist as a workflow.
+- **OFN Super-Admin Guide** — https://ofn-user-guide.gitbook.io/ofn-super-admin-guide — for those running their own OFN instance.
+- **OFN Developer Site** — https://dev.openfoodnetwork.org/ — developer-facing material outside of this AGENTS file.
+
+Both user guides are GitBook-hosted; their sitemaps can be fetched and the per-page content scraped. The `idea-refiner` tool (https://gitlab.com/our-sci/software/idea-refiner) caches the user guide and consults it before agents respond, to avoid recommending features that already exist.
+
+If an agent has no way to query the docs directly, it should at minimum *acknowledge* that the docs exist and tell the user to check there, rather than asserting "OFN does not have this feature."