ecoportal-api 0.10.16 → 0.10.17

data/.claude/settings.json

@@ -0,0 +1,128 @@
+{
+  "permissions": {
+    "defaultMode": "acceptEdits",
+    "allow": [
+      "Bash(bundle exec rspec *)",
+      "Bash(bundle exec rspec)",
+      "Bash(bundle exec rubocop *)",
+      "Bash(bundle exec rubocop)",
+      "Bash(git status)",
+      "Bash(git log *)",
+      "Bash(git diff *)",
+      "Bash(git diff)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git branch *)",
+      "Bash(git checkout *)",
+      "Bash(git push -o merge_request.create*)",
+      "Bash(git push -u origin *)",
+      "Bash(git push origin HEAD*)",
+      "Bash(git push *)",
+      "Bash(bundle install)",
+      "Bash(bundle exec *)",
+      "Edit(.ai-assistance/**)",
+      "Read(.git/**)",
+      "WebFetch(domain:anthropic.com)",
+      "WebFetch(domain:docs.anthropic.com)"
+    ],
+    "deny": [
+      "Bash(git push --force*)",
+      "Bash(git push * --force*)",
+      "Bash(git push --force-with-lease*)",
+      "Bash(git push * --force-with-lease*)",
+      "Bash(git push origin main*)",
+      "Bash(git push origin master*)",
+      "Bash(git push * origin main*)",
+      "Bash(git push * origin master*)",
+      "Bash(rm -rf *)",
+      "Bash(cat .env*)",
+      "Read(.env*)",
+      "Read(./secrets/**)",
+      "Edit(.env*)",
+      "Edit(//System/**)",
+      "Edit(//Library/**)",
+      "Edit(~/Library/**)",
+      "Edit(//usr/**)",
+      "Edit(//etc/**)",
+      "Edit(//bin/**)",
+      "Edit(//sbin/**)",
+      "Edit(//boot/**)",
+      "Edit(//c/Windows/**)",
+      "Edit(//c/Program Files/**)",
+      "Edit(//c/Program Files (x86)/**)",
+      "Read(~/.ssh/**)",
+      "Read(~/.aws/**)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .ai-assistance/scripts/bridge-init.sh 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "command": "bash .ai-assistance/scripts/bridge-inbox-check.sh 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "command": "bash .ai-assistance/scripts/surface-procedural.sh"
+          },
+          {
+            "type": "command",
+            "command": "bash .ai-assistance/scripts/dirty-tree-guard.sh 2>/dev/null || true"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .ai-assistance/scripts/observe-session.sh"
+          },
+          {
+            "type": "command",
+            "command": "bash .ai-assistance/scripts/dirty-tree-guard.sh 2>/dev/null || true"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .ai-assistance/scripts/protect-host-paths.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .ai-assistance/scripts/log-skill-usage.sh 2>/dev/null || true"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .ai-assistance/scripts/log-mcp-access.sh 2>/dev/null || true"
+          }
+        ]
+      }
+    ]
+  }
+}

data/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to this project will be documented in this file.
 
-## [0.10.17] - 2026-06-xx
+## [0.10.17] - 2026-08-08
 
 ### Added
 
@@ -10,11 +10,14 @@ All notable changes to this project will be documented in this file.
 
 ### Fixed
 
-## [0.10.16] - 2026-06-05
-
-### Added
+- `WithRetry` never retried timeouts: `HTTP::TimeoutError` (and so `HTTP::ConnectTimeoutError`)
+  is a sibling of `HTTP::ConnectionError` in the `http` gem hierarchy, not a subclass — a
+  transient connect/read/write timeout propagated immediately and killed whole batches mid-loop
+  (live-confirmed on the Farmers native card, 2026-07-30). Added `HTTP::TimeoutError` to
+  `HANDLED_CONNECTION_ERRORS`; applies to all downstream gems that inherit this retry layer
+  (`ecoportal-api-v2`, `ecoportal-api-graphql`, `eco-helpers`).
 
-### Changed
+## [0.10.16] - 2026-06-05
 
 ### Fixed
 

data/CLAUDE.md

@@ -1,71 +1,95 @@
-# CLAUDE.md — ecoportal-api
-
-AI agent instructions for this repository.
-
-**Cross-cutting architecture context lives in `ecoportal-api-graphql` — see its `CLAUDE.md` and `.claude/` folder for the full dependency map, project history, and shared skills.**
-
----
-
-## Repository Role
-
-`ecoportal-api` is the **foundational REST API gem** in the EcoPortal Ruby stack. It provides authentication, HTTP client infrastructure, org context, and the `Ecoportal::API::Common` namespace that all downstream gems build on.
-
-**Position in chain:**
-```
-ecoportal-api          ← THIS REPO
-      ↓
-ecoportal-api-v2
-      ↓
-ecoportal-api-graphql
-      ↓
-eco-helpers
-```
-
-**Remote:** https://gitlab.ecoportal.co.nz/ecoportal/ecoportal-api.git
-
----
-
-## Key Folder Layout
-
-```
-lib/ecoportal/api/
-  common/              Shared infrastructure (client, logging, response, batch, hash_diff)
-    client/            HTTP client — rate throttling, retries, timeouts, APM, error handling
-  errors/              Shared error classes
-  internal/            Internal API resources (people, permissions, schema, login providers)
-  v1/                  REST API v1 resources (people, schema, jobs)
-  logger.rb            Shared logger
-  version.rb           Gem version
-```
-
----
-
-## Namespace
-
-`Ecoportal::API` — specifically:
-- `Ecoportal::API::Common` — shared base classes (consumed by `ecoportal-api-v2` and `ecoportal-api-graphql`)
-- `Ecoportal::API::Internal` — internal API endpoints
-- `Ecoportal::API::V1` — v1 REST endpoints
-
----
-
-## Key Concerns
-
-- `Common::Client` — base HTTP client with rate throttling, retry logic, timeouts, and APM integration. All downstream clients inherit or wrap this.
-- `Common::BaseModel` / `Common::BaseClass` — base model classes. `ecoportal-api-v2` extends these heavily.
-- Changes to `Common::` affect **all downstream gems** — treat as a public API.
-
----
-
-## Backwards Compatibility
-
-Changes to `Ecoportal::API::Common::*` propagate to `ecoportal-api-v2`, `ecoportal-api-graphql`, and `eco-helpers`. Any breaking change must be coordinated across the chain.
-
----
-
-## Running Tests
-
-```bash
-bundle install
-bundle exec rspec
-```
+# CLAUDE.md — ecoportal-api
+
+AI agent instructions for this repository.
+
+**Cross-cutting architecture context lives in `ecoportal-api-graphql` — see its `CLAUDE.md` and `.claude/` folder for the full dependency map, project history, and shared skills.**
+
+---
+
+## Read these first — every session
+
+```
+docs/worklog.md      <- current state, blockers, open questions
+.ai-assistance/local/paths.json   <- local paths to ep-ai-standards + sibling repos (gitignored)
+```
+
+---
+
+## Repository Role
+
+`ecoportal-api` is the **foundational REST API gem** in the EcoPortal Ruby stack. It provides authentication, HTTP client infrastructure, org context, and the `Ecoportal::API::Common` namespace that all downstream gems build on.
+
+**Position in chain:**
+```
+ecoportal-api          ← THIS REPO
+      ↓
+ecoportal-api-v2
+      ↓
+ecoportal-api-graphql
+      ↓
+eco-helpers
+```
+
+**Remote:** https://gitlab.ecoportal.co.nz/ecoportal/ecoportal-api.git
+
+---
+
+## Key Folder Layout
+
+```
+lib/ecoportal/api/
+  common/              Shared infrastructure (client, logging, response, batch, hash_diff)
+    client/            HTTP client — rate throttling, retries, timeouts, APM, error handling
+  errors/              Shared error classes
+  internal/            Internal API resources (people, permissions, schema, login providers)
+  v1/                  REST API v1 resources (people, schema, jobs)
+  logger.rb            Shared logger
+  version.rb           Gem version
+```
+
+---
+
+## Namespace
+
+`Ecoportal::API` — specifically:
+- `Ecoportal::API::Common` — shared base classes (consumed by `ecoportal-api-v2` and `ecoportal-api-graphql`)
+- `Ecoportal::API::Internal` — internal API endpoints
+- `Ecoportal::API::V1` — v1 REST endpoints
+
+---
+
+## Key Concerns
+
+- `Common::Client` — base HTTP client with rate throttling, retry logic, timeouts, and APM integration. All downstream clients inherit or wrap this.
+- `Common::BaseModel` / `Common::BaseClass` — base model classes. `ecoportal-api-v2` extends these heavily.
+- Changes to `Common::` affect **all downstream gems** — treat as a public API.
+
+---
+
+## Backwards Compatibility
+
+Changes to `Ecoportal::API::Common::*` propagate to `ecoportal-api-v2`, `ecoportal-api-graphql`, and `eco-helpers`. Any breaking change must be coordinated across the chain.
+
+---
+
+## Running Tests
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+---
+
+## Token economy -- ENFORCED
+
+This gem shares one account-wide weekly token ceiling with every other AI-enabled
+repo. Keep sessions short and scoped -- end or reset one when a work item completes.
+Any background/subagent work MUST start from a fresh context (never a fork) with a
+self-contained task card naming an explicit model tier; never let a launched agent
+silently inherit this session's model. Delegated agents COMMIT but MUST NOT push or
+open MRs -- this session verifies independently, then pushes. Before briefing a task
+that depends on an external API, probe its real limits (endpoint, window/page size,
+pagination, scope) first -- do not let the agent discover them mid-task. Batch shell
+commands; avoid per-command round-trips or polling loops.
+Full standard: `standards/workflows/token-economy.md` in ep-ai-standards.

data/docs/self-docs/ARCHITECTURE.md

@@ -0,0 +1,145 @@
+---
+schema_version: "1.1"
+repo: "ecoportal-api"
+doc: architecture
+last_generated: "2026-07-23"
+source_head: "69bf8e3"
+review_status: draft
+---
+
+# Architecture -- ecoportal-api
+
+**Scope:** High-level structure only. No `.ai-assistance/code/` code-specs exist yet in this repo
+(scanner: `existing_context.code_specs` is empty) -- this section is derived directly from the
+`lib/` tree, not from a code-specs layer.
+
+## Top-level structure
+
+(From the scanner's `top_level_dirs`.)
+
+| Directory | Role |
+|---|---|
+| `lib/` | The gem source (`Ecoportal::API` namespace: `common/`, `internal/`, `v1/`, `errors/`) |
+| `spec/` | RSpec test suite, mirrors the `lib/` namespace layout |
+| `bin/` | `bin/setup`, `bin/console` -- local dev helpers (from `README.md`) |
+| `docs/` | This self-docs set + `docs/worklog.md` (session handoff log) |
+| `.ai-assistance/` | AI tooling scaffold (skills, scripts, bridge, capabilities) -- most-touched
+  directory after `lib/` in the last 50 commits (scanner `activity_clusters`: `.ai-assistance` 27
+  touches vs `lib` 28) |
+| `.claude/` | Committed Claude Code settings (`settings.json`: permissions + hooks) |
+| `.ruby-lsp` | Ruby LSP cache/config directory |
+
+## Key components
+
+- `Ecoportal::API::Common` (`lib/ecoportal/api/common.rb` + `common/`) -- shared base classes and
+  infrastructure consumed by every downstream gem:
+  - `Common::Client` (`common/client.rb`) -- the HTTP client (wraps the `http` gem), with
+    sub-modules for rate throttling (`client/rate_throttling.rb`, `client/throughput*.rb`),
+    retries (`client/with_retry.rb`), timeouts (`client/time_out.rb`), error handling
+    (`client/error*.rb`), and optional Elastic APM reporting (`client/elastic_apm_integration.rb`).
+  - `Common::BaseModel` / `Common::BaseClass` (`common/base_model.rb`, `common/base_class.rb`) --
+    base model classes; `ecoportal-api-v2` extends these heavily (per `CLAUDE.md`).
+  - `Common::Response` / `Common::WrappedResponse`, `Common::BatchOperation` /
+    `Common::BatchResponse`, `Common::HashDiff`, `Common::Logging`, `Common::DocHelpers`.
+- `Ecoportal::API::Internal` (`lib/ecoportal/api/internal/`) -- internal API resources: people,
+  person/person_details/person_schema(s), permissions, policy groups, login providers, preferences,
+  schema fields, account.
+- `Ecoportal::API::V1` (`lib/ecoportal/api/v1/`) -- v1 REST resources: people, person(s),
+  person_schema(s), schema_field(s), and async jobs (`v1/job.rb`, `job/awaiter*`, `job/status.rb`).
+- `Ecoportal::API::Errors` (`lib/ecoportal/api/errors/`) -- shared error base + timeout error
+  classes.
+
+(Evidence: `CLAUDE.md` "Key Folder Layout"/"Key Concerns", cross-checked against the actual
+`lib/` file listing.)
+
+## How they fit
+
+A consumer requires `ecoportal/api`, constructs a `Common::Client` with an API key/host/version,
+and calls into `Internal::*` or `V1::*` resource classes, which use `Common::BaseModel`/
+`Common::BaseClass` for their data shape and go through `Common::Client` for all HTTP traffic
+(retry/throttle/timeout/APM are cross-cutting concerns applied at the client layer, not per
+resource). `Common::Response`/`WrappedResponse` normalise API responses back into Ruby objects for
+the resource classes.
+
+## Entry points
+
+- `lib/ecoportal/api.rb` -- the gem root; `require 'dotenv/load'` runs on require, so a `.env` file
+  in the consuming process is picked up automatically.
+- `bin/console` -- interactive `pry`/IRB console for local experimentation (`README.md`).
+- `bin/setup` -- installs dependencies for local development.
+- There is no server/CLI/Lambda entry point -- this is a library, not a standalone service
+  (no `cdk.json`, `Dockerfile`, `manifest.json`, or `config/application.rb` found at the repo
+  root).
+
+## Diagrams
+
+Only one diagram category is evidenced in this repo. The CI/CD pipeline graph, the privacy
+data-flow diagram, and the deployment-topology diagram are each OMITTED rather than fabricated,
+per the rule "2 real diagrams beat 4 where two are invented" (here: 1 real diagram beats 4 where 3
+would be invented):
+
+- **CI/CD pipeline graph:** omitted -- no `.gitlab-ci.yml`, `Jenkinsfile`, or `.github/workflows/`
+  found in this repo (scanner `structure.ci_files` is empty). unknown -- needs owner input on
+  whether CI runs from an external/inherited GitLab CI template not present as a file in this
+  working tree.
+- **Data-flow (privacy-relevant paths):** omitted -- no scrub/PII-transform module exists in
+  `lib/`; the gem's own `.ai-assistance/scripts/scrub.py` is AI-tooling-session scrubbing, not a
+  data path this gem's runtime code implements. See `COMPLIANCE.md`.
+- **Deployment topology:** omitted -- no CDK/Terraform/Dockerfile/docker-compose file exists in
+  this repo (it is a library gem, not a deployed service).
+
+### Component / layer diagram
+
+The client (`Common::Client`) is the single HTTP boundary; everything above it is resource/model
+code that never talks HTTP directly. APM reporting is an optional side-channel off the client,
+gated by `ElasticAPM.running?` and a rescued `StandardError` (fails open to "APM disabled", not to
+a crash) -- see `client/elastic_apm_integration.rb`.
+
+```mermaid
+flowchart TD
+    subgraph Consumers["Downstream gems (ecoportal-api-v2, ecoportal-api-graphql, eco-helpers)"]
+        C[Consumer code]
+    end
+    subgraph Resources["Ecoportal::API::Internal / V1 resources"]
+        R[Internal::* and V1::* resource classes]
+    end
+    subgraph CommonLayer["Ecoportal::API::Common"]
+        BM[BaseModel / BaseClass]
+        CL[Client]
+        RT[RateThrottling / Throughput]
+        WR[WithRetry]
+        TO[TimeOut]
+        RESP[Response / WrappedResponse]
+    end
+    EXT[["ecoPortal API (live.ecoportal.com)"]]
+    APM[["Elastic APM (Elastic Cloud, optional)"]]
+
+    C --> R
+    R --> BM
+    R --> CL
+    CL --> RT
+    CL --> WR
+    CL --> TO
+    CL --> RESP
+    CL -->|HTTPS, api_key| EXT
+    CL -.->|error telemetry, opt-in| APM
+```
+
+Sources: `lib/ecoportal/api/common/client.rb`, `lib/ecoportal/api/common/client/*.rb`,
+`lib/ecoportal/api/common/base_model.rb`, `lib/ecoportal/api/internal/`, `lib/ecoportal/api/v1/`,
+`CLAUDE.md`.
+
+## Build / test tooling
+
+- Build: Bundler/RubyGems (`Rakefile` -- `bundler/gem_tasks`; `bundle exec rake install` /
+  `rake release` per `README.md`).
+- Tests: RSpec (`Rakefile` -- `RSpec::Core::RakeTask`; run via `bundle exec rspec` per `CLAUDE.md`
+  and `README.md`'s `rake spec`). Lint: RuboCop (`RuboCop::RakeTask`, `.rubocop.yml`). Docs: YARD
+  (`YARD::Rake::YardocTask`, `.yardopts`). `rake` (no args) runs RuboCop then RSpec.
+- CI: none found in this repo (scanner `structure.ci_files` is empty; see "Diagrams" above).
+
+## Links to detailed docs
+
+None yet -- `.ai-assistance/code/` has no code-specs for this repo (scanner:
+`existing_context.code_specs` is empty). Running the `code-specs` skill would give this section
+real per-area links instead of this note.

data/docs/self-docs/CHANGES.jsonl

@@ -0,0 +1,7 @@
+{"ts": "2026-07-23T10:50:08Z", "file": "docs/self-docs/OVERVIEW.md", "change": "created", "from_hash": null, "to_hash": "a819fa9d200c7ab7"}
+{"ts": "2026-07-23T10:50:08Z", "file": "docs/self-docs/ARCHITECTURE.md", "change": "created", "from_hash": null, "to_hash": "49a7df216c5bdc07"}
+{"ts": "2026-07-23T10:50:08Z", "file": "docs/self-docs/CONVENTIONS.md", "change": "created", "from_hash": null, "to_hash": "f45075d3f3ca043c"}
+{"ts": "2026-07-23T10:50:08Z", "file": "docs/self-docs/INTEGRATIONS.md", "change": "created", "from_hash": null, "to_hash": "b5cb184b9e829040"}
+{"ts": "2026-07-23T10:50:08Z", "file": "docs/self-docs/STATUS.md", "change": "created", "from_hash": null, "to_hash": "147657c19c13c34e"}
+{"ts": "2026-07-23T10:50:08Z", "file": "docs/self-docs/COMPLIANCE.md", "change": "created", "from_hash": null, "to_hash": "802e24afbd20f486"}
+{"ts": "2026-07-23T10:50:08Z", "file": "docs/self-docs/OPERATIONS.md", "change": "created", "from_hash": null, "to_hash": "475c09e0348a9187"}

data/docs/self-docs/COMPLIANCE.md

@@ -0,0 +1,66 @@
+---
+schema_version: "1.1"
+repo: "ecoportal-api"
+doc: compliance
+last_generated: "2026-07-23"
+source_head: "69bf8e3"
+review_status: draft   # audit answers MUST come from 'reviewed' docs only -- a human sets this
+---
+
+# Compliance -- ecoportal-api
+
+**Purpose:** the audit / privacy / ISO-27001 surface for this project. It lets ROVO (over the EP Projects
+Register) answer compliance questions across the fleet. **Trust rule:** everything here separates
+EVIDENCE (a fact or link) from INTENT (planned); a reviewer must set `review_status: reviewed` before an
+answer built on this doc is used for audit or re-certification -- a confident answer on unreviewed content
+would mislead an auditor.
+
+## ISO 27001
+
+| Control area | Status (evidence / planned) | Evidence link |
+|---|---|---|
+| Access control (credential handling) | EVIDENCE (partial) | `api_key` passed at `Client.new` call site, sent as `X-ApiKey` header (`lib/ecoportal/api/common/client.rb`); the key's storage/rotation is the CONSUMER's responsibility, not this gem's -- this gem does not persist credentials |
+| Secure engineering (lint/test gate) | EVIDENCE (partial) | `.rubocop.yml`, RSpec suite in `spec/`, `rake` default task runs RuboCop then RSpec (`Rakefile`) -- but no CI file enforces this automatically pre-merge (see `ARCHITECTURE.md` Diagrams section); PLANNED/unknown whether merge is gated on these passing |
+| Dependency management | EVIDENCE | `ecoportal-api.gemspec` pins runtime deps with version constraints; `Gemfile.lock` exists but is gitignored (`.gitignore`: "it's a gem, ignore the lockfile") |
+| Third-party telemetry vendor review | unknown -- needs owner input | Elastic APM is used (see below); whether it has been through a formal vendor/DPA review is not evidenced in this repo |
+| Incident/error monitoring | EVIDENCE (partial) | `ElasticApmIntegration` reports `UnexpectedServerError`s only, fails open/silent on APM-unavailable (`client/elastic_apm_integration.rb`) |
+
+## Data handled
+
+| Data class (none/team/customer/PII) | What / where | Treatment + retention | Exposed? (how) |
+|---|---|---|---|
+| Customer/employee data (potentially PII) | Person records (`Internal::Person`, `V1::Person`, schema fields) -- this gem transports them between the consuming application and the ecoPortal API; it does not persist them itself (no database/store in this repo) | In-memory only within this gem's process lifetime; retention is entirely the CONSUMER application's responsibility, not this gem's | Not exposed by this gem directly -- exposure depends on what the consuming application does with the returned model objects. unknown -- needs owner input on which consumers log/persist full response bodies |
+| APM telemetry | Error class/status metadata sent to Elastic Cloud on unexpected server errors (`transaction_sample_rate: 0.1`) | Elastic Cloud-side retention -- unknown -- needs owner input (governed by ecoPortal's Elastic Cloud account settings, not this repo) | Sent to Elastic Cloud (`https://<account>.apm.<region>.aws.cloud.es.io`), see Vendors below |
+
+## Third-party vendors in the data path
+
+| Vendor | What data | Disclosed to end users? | Notes |
+|---|---|---|---|
+| Elastic (Elastic Cloud / Elastic APM) | Error/transaction telemetry, `transaction_sample_rate: 0.1`, only for unexpected server error responses; scoped by `ELASTIC_APM_*` env vars, defaults to `ap-southeast-2` region | unknown -- needs owner input | Optional: disables itself silently (`rescue StandardError`) if unavailable or unconfigured -- does not fail the host application (`elastic_apm_integration.rb`) |
+| RubyGems.org | Gem package (source code, no runtime customer data) at release time | N/A -- public package registry | `rubygems_mfa_required: true` set in gemspec |
+
+No other outbound third-party vendor call was found in `lib/` (only `http`, `dotenv`,
+`elastic-apm`, `rate_throttle_client` are runtime dependencies per the gemspec).
+
+## PII / data-leak controls
+
+- No PII-scrubbing module exists in this gem's runtime code (`lib/`) -- this gem is a thin HTTP
+  client/model layer; it does not implement scrubbing because it is not itself an ingestion/storage
+  system. Responsibility for PII handling sits with the consuming application. This is an
+  observation of current reality, not a judgement that it should change -- unknown -- needs owner
+  input on whether that responsibility split is the intended design or a gap.
+- `.ai-assistance/scripts/scrub.py` exists in this repo, but it scrubs AI-tooling session
+  artefacts (per the ecoPortal AI-standards convention), not this gem's runtime data path -- do not
+  conflate the two.
+- Credential handling: the `api_key` is passed in by the caller at construction time and is not
+  logged by default (`Common::Logging` was not audited line-by-line in this run for redaction
+  behaviour) -- unknown -- needs owner input on whether `api_key` can ever land in a log line.
+
+## AI-generated content
+
+- Externally-exposed AI content: no -- this is a code library with no output surface that presents
+  AI-generated content to end users.
+- Marked as AI-generated: N/A.
+- Review process: N/A. This self-docs set ITSELF is AI-generated (by the `project-self-docs`
+  skill) and carries `review_status: draft` until a human reviews it -- see this file's own
+  frontmatter.

data/docs/self-docs/CONVENTIONS.md

@@ -0,0 +1,74 @@
+---
+schema_version: "1.1"
+repo: "ecoportal-api"
+doc: conventions
+last_generated: "2026-07-23"
+source_head: "69bf8e3"
+review_status: draft
+---
+
+# Conventions -- ecoportal-api
+
+**Source of truth:** `.rubocop.yml` (root, plus `spec/.rubocop.yml` for the spec directory),
+`.editorconfig` not found, `.solargraph.yml`/`.ruby-lsp/` (editor tooling, not style rules). No
+`ai-discovery` `conventions.md` exists yet in `.ai-assistance/local/` (scanner:
+`existing_context.conventions` is `null`) -- this doc is derived directly from `.rubocop.yml` and
+observed git history instead.
+
+## Code style
+
+(From `.rubocop.yml`, root.)
+
+- Target Ruby version: 3.2 (`AllCops.TargetRubyVersion: 3.2`; gemspec requires `>= 3.2.2`)
+- `NewCops: enable` -- new RuboCop cops are opted in by default
+- Notable size limits: `Metrics/ClassLength` max 500, `Metrics/ModuleLength` max 300,
+  `Metrics/MethodLength` max 50, `Metrics/BlockLength` max 50 (heredoc/array/method_call each
+  count as one), `Metrics/AbcSize` max 30, `Metrics/ParameterLists` max 5,
+  `Metrics/CyclomaticComplexity`/`Metrics/PerceivedComplexity` max 30
+- `Style/HashSyntax`: `no_mixed_keys`, shorthand allowed either way
+- `Style/ClassAndModuleChildren`: disabled (compact nested-namespace style, e.g.
+  `class Ecoportal::API::Foo`, is allowed alongside nested `module`/`class` blocks)
+- Indentation/quotes/line-length: unknown -- needs owner input; not asserted by `.rubocop.yml`'s
+  cop list read so far and no `.editorconfig`/`.rubocop.yml` `Layout/*` overrides were inspected
+  beyond what is quoted above -- do not infer from a single file without checking further.
+
+## Branch naming
+
+Observed from the local + remote branch list (`git branch -a`): `feat/<slug>`, `fix/<slug>`,
+`chore/<slug>`, `auto/<slug>` prefixes (e.g. `feat/deploy-project-self-docs`,
+`fix/migration-0013-scrub-settings-hygiene`, `chore/ai-standards-alignment-1.9.1`,
+`auto/claude-md-startup-reads`). This matches the `type/slug` convention used across the
+ecoPortal AI-tooling fleet (see `ep-ai-standards` branching model). Numeric-only branches also
+exist from pre-AI-tooling history (e.g. `remotes/origin/19-ecoportal-api-common-basemodel-...`) --
+treat those as legacy, not the current convention.
+
+## Commit message style
+
+Observed from `git log --oneline -20`: `type: message` or `type(scope): message`, e.g.
+`fix: migration 0013 -- canonical scrub.py + kit refresh + settings hygiene`,
+`chore(ai): confirm alignment with ep-ai-standards v1.9.1`,
+`feat(ai): deploy project-self-docs skill (self-documentation, run in-repo)`. Feature-branch work
+merges via GitLab merge commits (`Merge branch '<branch>' into 'master'`).
+
+## Test conventions
+
+- Runner: RSpec (`bundle exec rspec`, `.rspec` config file, `.rspec_status` present for
+  failure-tracking -- gitignored per `.gitignore`).
+- Placement: `spec/` mirrors the `lib/` namespace (e.g. `lib/ecoportal/api/internal/person.rb` ->
+  `spec/ecoportal/api/internal/person_*_spec.rb`); fixture JSON files sit alongside their specs
+  (e.g. `spec/ecoportal/api/internal/person_employee.json`).
+- Coverage expectations: unknown -- needs owner input; no coverage tool/threshold config
+  (e.g. SimpleCov) was found in the files inspected.
+- `.rubocop.yml` in `spec/` scopes lint rules separately for specs (file present but not read in
+  detail here -- unknown -- needs owner input on spec-specific cop overrides).
+
+## Project-specific rules
+
+From `CLAUDE.md`:
+
+- Changes to `Ecoportal::API::Common::*` are treated as a public API -- they propagate to
+  `ecoportal-api-v2`, `ecoportal-api-graphql`, and `eco-helpers`; any breaking change must be
+  coordinated across that chain, not made unilaterally in this repo.
+- Cross-cutting architecture/dependency context for the wider gem chain lives in
+  `ecoportal-api-graphql`'s `CLAUDE.md` and `.claude/` folder, not duplicated here.
+- `docs/worklog.md` is the required first read every AI session (session handoff log).