ecoportal-api-graphql 1.3.11 → 1.3.13

data/.claude/settings.json

@@ -1,146 +1,150 @@
-{
-  "permissions": {
-    "defaultMode": "auto",
-    "allowedTools": [
-      "Read"
-    ],
-    "permissionRules": [
-      {
-        "tool": "Write",
-        "pattern": "/**",
-        "action": "allow"
-      },
-      {
-        "tool": "StrReplace",
-        "pattern": "/**",
-        "action": "allow"
-      }
-    ],
-    "allow": [
-      "WebFetch(domain:anthropic.com)",
-      "WebFetch(domain:npmjs.com)",
-      "Write(.glaudeignore)",
-      "Update(.glaudeignore)",
-      "Bash(rm .ai-assistance/bridge/LOCK)",
-      "Read(.git/**)",
-      "Read(**/rubygems/**)",
-      "Write(*.md)",
-      "Edit(.ai-assistance/**)",
-      "Update(.ai-assistance/**)",
-      "Write(.ai-assistance/**)",
-      "Write(lib/**)",
-      "Write(spec/**)",
-      "Bash(git status)",
-      "Bash(git diff *)",
-      "Bash(git log *)",
-      "Bash(git add *)",
-      "Bash(git commit *)",
-      "PowerShell(git status)",
-      "PowerShell(git diff *)",
-      "PowerShell(git log *)",
-      "PowerShell(git add *)",
-      "PowerShell(git commit *)",
-      "Bash(npm test)",
-      "Bash(npm run lint)",
-      "Bash(npm run build)",
-      "Bash(vitest *)",
-      "Bash(jest *)",
-      "PowerShell(npm test)",
-      "PowerShell(npm run lint)",
-      "PowerShell(npm run build)",
-      "Bash(black .)",
-      "Bash(pytest)",
-      "Bash(python -m unittest)",
-      "Bash(ruff check *)",
-      "Bash(bundle exec rspec *)",
-      "Bash(bundle exec rubocop *)",
-      "PowerShell(pytest)",
-      "PowerShell(python -m unittest)",
-      "PowerShell(ruff check *)",
-      "PowerShell(bundle exec rspec *)",
-      "PowerShell(bundle exec rubocop *)",
-      "Bash(node .ai-assistance/scripts/token-logger.js)",
-      "Bash(node .ai-assistance/scripts/token-session-start.js)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git status*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git log*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git diff*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git show*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git branch*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git fetch*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git checkout*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git switch*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git add*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git commit*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git rev-parse*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git merge-base*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git ls-remote*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git stash*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && bundle exec rspec*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && bundle exec rake test*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && bundle exec rubocop*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && bundle install*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git status*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git log*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git diff*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git show*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git branch*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git fetch*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git checkout*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git switch*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git add*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git commit*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git rev-parse*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git merge-base*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git ls-remote*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git stash*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && bundle exec rake test*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && bundle exec rubocop*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && bundle install*)"
-    ],
-    "deny": [
-      "Read(*.env)",
-      "Read(./.env*)",
-      "Read(./secrets/**)",
-      "Bash(*cat *.env*)",
-      "Bash(*grep *.env*)",
-      "Bash(printenv*)",
-      "Bash(env)",
-      "Write(.git/*)",
-      "Edit(.git/*)",
-      "Bash(git push *)",
-      "Bash(rm -rf *)"
-    ]
-  },
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash .ai-assistance/scripts/bridge-init.sh 2>/dev/null || true"
-          },
-          {
-            "type": "command",
-            "command": "node .ai-assistance/scripts/token-session-start.js 2>/dev/null || true"
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node .ai-assistance/scripts/token-logger.js 2>/dev/null || true"
-          },
-          {
-            "type": "command",
-            "command": "bash scripts/auto-worker-scheduler.sh 2>/dev/null || true"
-          }
-        ]
-      }
-    ]
-  }
-}
+{
+  "permissions": {
+    "defaultMode": "auto",
+    "allowedTools": [
+      "Read"
+    ],
+    "permissionRules": [
+      {
+        "tool": "Write",
+        "pattern": "/**",
+        "action": "allow"
+      },
+      {
+        "tool": "StrReplace",
+        "pattern": "/**",
+        "action": "allow"
+      }
+    ],
+    "allow": [
+      "WebFetch(domain:anthropic.com)",
+      "WebFetch(domain:npmjs.com)",
+      "Write(.glaudeignore)",
+      "Update(.glaudeignore)",
+      "Bash(rm .ai-assistance/bridge/LOCK)",
+      "Read(.git/**)",
+      "Read(**/rubygems/**)",
+      "Write(*.md)",
+      "Edit(.ai-assistance/**)",
+      "Update(.ai-assistance/**)",
+      "Write(.ai-assistance/**)",
+      "Write(lib/**)",
+      "Write(spec/**)",
+      "Bash(git status)",
+      "Bash(git diff *)",
+      "Bash(git log *)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "PowerShell(git status)",
+      "PowerShell(git diff *)",
+      "PowerShell(git log *)",
+      "PowerShell(git add *)",
+      "PowerShell(git commit *)",
+      "Bash(npm test)",
+      "Bash(npm run lint)",
+      "Bash(npm run build)",
+      "Bash(vitest *)",
+      "Bash(jest *)",
+      "PowerShell(npm test)",
+      "PowerShell(npm run lint)",
+      "PowerShell(npm run build)",
+      "Bash(black .)",
+      "Bash(pytest)",
+      "Bash(python -m unittest)",
+      "Bash(ruff check *)",
+      "Bash(bundle exec rspec *)",
+      "Bash(bundle exec rubocop *)",
+      "PowerShell(pytest)",
+      "PowerShell(python -m unittest)",
+      "PowerShell(ruff check *)",
+      "PowerShell(bundle exec rspec *)",
+      "PowerShell(bundle exec rubocop *)",
+      "Bash(node .ai-assistance/scripts/token-logger.js)",
+      "Bash(node .ai-assistance/scripts/token-session-start.js)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git status*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git log*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git diff*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git show*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git branch*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git fetch*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git checkout*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git switch*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git add*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git commit*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git rev-parse*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git merge-base*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git ls-remote*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && git stash*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && bundle exec rspec*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && bundle exec rake test*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && bundle exec rubocop*)",
+      "Bash(cd C:/ruby_scripts/git/graphlient && bundle install*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git status*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git log*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git diff*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git show*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git branch*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git fetch*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git checkout*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git switch*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git add*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git commit*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git rev-parse*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git merge-base*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git ls-remote*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && git stash*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && bundle exec rake test*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && bundle exec rubocop*)",
+      "Bash(cd C:/ruby_scripts/git/graphql-client && bundle install*)"
+    ],
+    "deny": [
+      "Read(*.env)",
+      "Read(./.env*)",
+      "Read(./secrets/**)",
+      "Bash(*cat *.env*)",
+      "Bash(*grep *.env*)",
+      "Bash(printenv*)",
+      "Bash(env)",
+      "Write(.git/*)",
+      "Edit(.git/*)",
+      "Bash(git push *)",
+      "Bash(rm -rf *)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .ai-assistance/scripts/bridge-init.sh 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "command": "node .ai-assistance/scripts/token-session-start.js 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "command": "bash .ai-assistance/scripts/bridge-inbox-check.sh 2>/dev/null || true"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .ai-assistance/scripts/token-logger.js 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "command": "bash scripts/auto-worker-scheduler.sh 2>/dev/null || true"
+          }
+        ]
+      }
+    ]
+  }
+}

data/.gitlab-ci.yml

@@ -0,0 +1,45 @@
+# CI pipeline for ecoportal-api-graphql
+#
+# First automated check on merge requests. Runs the RSpec suite NON-BLOCKING
+# (allow_failure: true) — it reports pass/fail status without gating merges.
+# Rationale (2026-07-10): add visibility now; tighten to a blocking gate later
+# once the suite is reliably green on a clean runner.
+#
+# Live/AI specs (tagged :live) are excluded: they need ANTHROPIC_API_KEY + network.
+# They already self-skip when the key is absent, but ~live keeps the runner off
+# that path entirely.
+#
+# NOTE: graphlient resolves from a git fork (see Gemfile); ecoportal-api / -v2 come
+# from rubygems. If a required floor (e.g. ecoportal-api-v2 >= 3.3.3) is not yet
+# published, `bundle install` may fail on the runner — because this job is
+# allow_failure, that surfaces as a warning rather than blocking the MR.
+
+workflow:
+  rules:
+    # Merge-request pipelines.
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    # Avoid a duplicate branch pipeline when an MR is already open for the branch.
+    - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'
+      when: never
+    # Branch pipelines (incl. main/master pushes and feature branches without an MR).
+    - if: '$CI_COMMIT_BRANCH'
+
+stages:
+  - test
+
+rspec:
+  stage: test
+  image: ruby:3.2.2
+  allow_failure: true          # non-blocking: surface failures, do not gate merges
+  variables:
+    BUNDLE_PATH: vendor/bundle  # cache installed gems between pipelines
+  cache:
+    key: "ruby-322-bundle"
+    paths:
+      - vendor/bundle
+  before_script:
+    - ruby -v
+    - gem install bundler
+    - bundle install --jobs "$(nproc)" --retry 3
+  script:
+    - bundle exec rspec --tag ~live --format progress

data/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.3.13] - 2026-07-12
+
+Reliability: the GraphQL `HttpClient` now inherits the **same request-resilience
+contingencies as the REST clients** instead of a bespoke, divergent request path.
+**Backwards-compatible** — `execute` returns the same parsed body and raises the same
+error classes; only the transport path changed.
+
+### Fixed
+
+- **`Common::GraphQL::HttpClient#execute` no longer bypasses the inherited
+  `Common::Client` pipeline.** It previously issued the POST raw
+  (`base_request.post`) and handled the response itself, so GraphQL requests got
+  **none** of the resilience baked into `ecoportal-api`'s client over the years —
+  a single **HTTP 429** (Cloudflare edge rate-limit, error `1015`) aborted the whole
+  run. `execute` now routes through `instrument` → `with_retry { rate_throttling }`,
+  gaining for free:
+  - **rate-limit backoff** via `rate_throttle_client` (default
+    `ExponentialIncreaseProportionalDecrease`) — 429s are throttled + retried, not fatal.
+  - **retry on 5xx / connection errors** (`WithRetry`, 5 attempts) + empty-body guard.
+  - timeouts, and (deep-)logging / APM instrumentation.
+  - `handle_http_response` now consumes the wrapped `Common::Response` (single body
+    read — also removes a latent double-read hazard). The GraphQL-errors-in-a-200-body
+    path (`ResponseError`) is unchanged.
+  This is convergence on the shared base, so any future contingency added to
+  `Common::Client` now applies to GraphQL automatically.
+
+## [1.3.12] - 2026-07-09
+
+Compat-layer correctness for register **field filters** + the native `SearchConf` field-filter DSL.
+**Backwards-compatible** — bug fixes (broken field filters returned 0 results) + additive methods;
+no public return type changed. (The `get_by_name`→collection contract change is intentionally **not**
+in this release — it is a breaking change parked on `feature/model-input-fixes` for a deliberate,
+signed-off future decision.)
+
+### Fixed
+
+- **`Compat::FilterTranslator`** now routes register **FIELD** filters to the backend-correct ES
+  operation (previously emitted the system-key operation → 0 results):
+  - Date FIELD (key `date.zXXXX`) → `range_date_filter` + `path: membranes.date` (system date keeps
+    `date_filter`).
+  - Select FIELD (key `select_str.zXXXX`) → `has_any_filter` / `doesnt_have_any_filter` +
+    `path: membranes.select_str` + `field_key: 'selected'` (system option key keeps
+    `one_of_filter`/`none_of_filter`).
+  - `exact_filter` no longer derives a `membranes.<type>` path for **system** keys
+    (`external_id`/`id`/`state`) — a spurious path produced term `membranes.external_id.external_id`
+    → 0 results (silent miss → dup-on-upsert). Register FIELD keys still get the nested path.
+  - Verified against the backend filter definitions; catalogued in
+    `.ai-assistance/code/filter_contract_matrix.md`.
+
+### Added
+
+- **`SearchConf` field-filter DSL:** `sc[:'date.zXXXX'].between/since/before` now emits
+  `range_date_filter` + `membranes.date` for register Date FIELDs; new `FieldRef#any_of` / `#none_of`
+  → `has_any_filter` / `doesnt_have_any_filter` (path + `field_key`) for register field value
+  membership (distinct from `one_of`, which ORs `exact_filter` for system keys).
+- **`get_by_id`** on `DataField::Collection` and `SectionCollection` (v2-compat find-by-id) — fixes
+  `NoMethodError` in consumers that resolve a field/section by id.
+
 ## [1.3.11] - 2026-07-04
 
 Template automatic **build & maintenance** engine (backwards-compatible — a self-contained new

data/CLAUDE.md

@@ -11,8 +11,18 @@ docs/worklog.md                          ← current state, blockers, open quest
 .ai-assistance/projects/<slug>/TODO.md   ← active project task list
 .ai-assistance/local/paths.json          ← local paths to sibling repos (gitignored — machine-specific)
 .ai-assistance/bridge/CLAUDE.md          ← bridge protocol: format, lifecycle, cross-repo requests
+.ai-assistance/bridge/inbox/             <- unread cross-project bridge messages (PENDING = unread); surfaced at session start by .ai-assistance/scripts/bridge-inbox-check.sh
+.ai-assistance/code/ecoPortal_architecture/  ← VERIFIED PLATFORM KNOWLEDGE — how the platform behaves
+                                            (data model, API layers, page/stage workflows, fields, search).
+                                            Read 00_overview_and_index first, then the area file for the
+                                            task at hand, BEFORE implementing platform logic. See ADR-012.
 ```
 
+> Platform behaviour is documented in `ecoPortal_architecture/` for a reason: do not infer a
+> stage/workflow/field rule from code alone when a verified note exists. If you confirm a new
+> platform fact, add it to the relevant doc with its evidence (`file:line` or "confirmed by
+> &lt;user&gt; on &lt;date&gt;") in the same session -- that tree is the durable, shared home.
+
 ---
 
 ## Repository Role
@@ -95,6 +105,7 @@ the developer explicitly requests it for a specific commit.
 | `spec-generation` | `.ai-assistance/skills/spec-generation/SKILL.md` | Generate RSpec specs for backwards-compat |
 | `refactor` | `.ai-assistance/skills/refactor/SKILL.md` | Identify and log refactoring opportunities |
 | `project-cycle` | `.ai-assistance/skills/project-cycle/SKILL.md` | Project planning, TODOs, decisions |
+| `procedural-memory` | `.ai-assistance/skills/procedural-memory/SKILL.md` | Distill recurring work routines and surface likely next steps |
 
 ---
 

data/docs/self-docs/ARCHITECTURE.md

@@ -0,0 +1,88 @@
+---
+schema_version: "1.1"
+repo: "ecoportal-api-graphql"
+doc: architecture
+last_generated: "2026-07-09"
+source_head: "3f7b877"
+review_status: draft
+---
+
+# Architecture -- ecoportal-api-graphql
+
+**Scope:** High-level structure only. Deep per-area detail lives in `.ai-assistance/code/`
+(`code-specs`); link to it rather than duplicating.
+
+## Top-level structure
+
+| Directory | Role |
+|---|---|
+| `lib/` | The gem source. `lib/ecoportal/api/graphql/` holds the layered client; `lib/ecoportal/api/common/graphql/` holds shared utilities (HTTP client, base model, helpers, patches). |
+| `spec/` | RSpec specs, mirroring the `lib/` structure. |
+| `tests/` | Manual integration test scripts (live-API characterization, not the RSpec suite). |
+| `bin/` | Development console / helper executables. |
+| `scripts/` | Token-offload and tooling scripts (see `scripts/CLAUDE.md`). |
+| `docs/` | Human docs, worklog, and this self-docs set. |
+| `.ai-assistance/` | AI agent resources: code-specs, project intent/TODOs, skills, bridge, conventions. |
+| `.claude/` | Claude Code settings and hooks for this repo. |
+
+## Key components
+
+Reused from `.ai-assistance/code/OVERVIEW.md` and `.ai-assistance/code/ecoPortal_architecture/`;
+not re-analysed here.
+
+- **Main class `Ecoportal::API::GraphQL`** (`lib/ecoportal/api/graphql.rb`) -- the public entry
+  point, instantiated with credentials (email, pass, org_id, host). Exposes builders and
+  convenience shortcuts per domain.
+- **`Common::GraphQL::Client`** (`lib/ecoportal/api/common/graphql/client.rb`) -- the HTTP layer,
+  extending `Graphlient::Client`. Handles auth (`AuthService`), org context, and timeouts;
+  `no_schema: true` is always passed, so schema introspection is disabled and queries are not
+  validated against a schema at build time.
+- **Layered namespace** under `Ecoportal::API::GraphQL::` (folder mirrors module exactly):
+  `Builder` (developer-facing facade per domain) -> `Query` / `Mutation` (operation definitions)
+  -> `Logic` (execution: base_query, base_model, payload, input, connection) -> `Fragment`
+  (fragment strings) -> `Model` (read-side response models), `Input` / `Payload` (write side) ->
+  `Base` (shared base classes), `Interface` (GraphQL interface types) -> `Common::GraphQL::Client`.
+- **`Compat::` layer** -- v2 compatibility shims (`Pages`, `Registers`, `StageView`,
+  `StageCollection`, etc.) that let `eco-helpers` treat `graphql` as a drop-in for the older `apiv2`
+  interface.
+- **`Diff::` and `Builder::TemplateBuilder`** -- the template build-and-maintenance engine
+  (self-version and cross-object diff, pairing engine + ledger, `Change`-to-`WorkflowCommand`
+  synthesis, unified BUILD emitter). This is where current development is concentrated.
+
+## How they fit
+
+A consumer instantiates `Ecoportal::API::GraphQL` with credentials, then calls a `Builder` for the
+domain it wants (page, template, action, contractor entity, location structure). The builder
+composes `Query`/`Mutation` operations, which the `Logic` layer executes through
+`Common::GraphQL::Client` over HTTP. Fragments are assembled at query build time
+(`BaseQuery#assemble_fragments` scans query strings for `...FragmentName` spreads). Responses parse
+into `Model` objects (read side); mutations take `Input` objects and return `Payload` objects
+(write side). The `Compat` layer re-exposes this so downstream `eco-helpers` scripts keep working
+unchanged.
+
+## Entry points
+
+- `require 'ecoportal/api-graphql'` loads `ecoportal-api-v2` (and transitively `ecoportal-api`),
+  the version file, `ecoportal/api/common.graphql`, then `ecoportal/api/graphql`.
+- Runtime entry is `Ecoportal::API::GraphQL.new(email:, pass:, org_id:, host:)`.
+
+## Build / test tooling
+
+- Build: RubyGems / Bundler. Gem spec: `ecoportal-api-graphql.gemspec`. Version constant:
+  `Ecoportal::API::GRAPQL_VERSION`.
+- Tests: RSpec (`bundle exec rspec`). Live AI tests are `--tag live` and require `ANTHROPIC_API_KEY`
+  loaded from `.env` via `dotenv`.
+- CI: no CI config file was detected at the repo root by the scanner (`ci_files: []`).
+  <!-- TODO(human): confirm whether CI runs elsewhere (e.g. GitLab CI defined outside root) or is absent. -->
+
+## Links to detailed docs
+
+- `.ai-assistance/code/OVERVIEW.md` -- gem overview, entry points, namespace convention.
+- `.ai-assistance/code/ecoPortal_architecture/00_overview_and_index.md` -- verified platform
+  knowledge index (data model, API layers, page/stage workflows, fields, search).
+- `.ai-assistance/code/ecoPortal_architecture/11_integration_gems.md` -- the integration gem stack.
+- `.ai-assistance/code/dependencies.md` -- full dependency map (remotes, fork relationships).
+- `.ai-assistance/code/diff_pairing_engine.md`, `.ai-assistance/code/diff_service_deep_dive.md`,
+  `.ai-assistance/code/template_diff_pairing_domain.md` -- the template diff/build engine.
+- `.ai-assistance/code/data_fields.md`, `.ai-assistance/code/graphql_domain_knowledge.md`,
+  `.ai-assistance/code/schema_analysis.md` -- data-field and schema detail.

data/docs/self-docs/CHANGES.jsonl

@@ -0,0 +1,12 @@
+{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/OVERVIEW.md", "change": "created", "from_hash": null, "to_hash": "a43c976a85ebfad6"}
+{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/ARCHITECTURE.md", "change": "created", "from_hash": null, "to_hash": "b0989977a912aab1"}
+{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/CONVENTIONS.md", "change": "created", "from_hash": null, "to_hash": "1649159eb799a7b8"}
+{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/INTEGRATIONS.md", "change": "created", "from_hash": null, "to_hash": "bae9f91748e33af1"}
+{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/STATUS.md", "change": "created", "from_hash": null, "to_hash": "08841d1d45eea2d6"}
+{"ts": "2026-07-06T11:15:00Z", "file": "docs/self-docs/OVERVIEW.md", "change": "updated", "from_hash": "a43c976a85ebfad6", "to_hash": "391055c9a6a687b9"}
+{"ts": "2026-07-06T11:15:00Z", "file": "docs/self-docs/ARCHITECTURE.md", "change": "updated", "from_hash": "b0989977a912aab1", "to_hash": "ad05f25b95b49c00"}
+{"ts": "2026-07-09T07:08:00Z", "file": "docs/self-docs/OVERVIEW.md", "change": "updated", "from_hash": "391055c9a6a687b9", "to_hash": "c403012498ab9247"}
+{"ts": "2026-07-09T07:08:00Z", "file": "docs/self-docs/INTEGRATIONS.md", "change": "updated", "from_hash": "bae9f91748e33af1", "to_hash": "d271ac76361e4638"}
+{"ts": "2026-07-09T07:08:00Z", "file": "docs/self-docs/STATUS.md", "change": "updated", "from_hash": "08841d1d45eea2d6", "to_hash": "1acf51a3e7822dfb"}
+{"ts": "2026-07-09T07:08:00Z", "file": "docs/self-docs/COMPLIANCE.md", "change": "created", "from_hash": null, "to_hash": "1e72c2356b4e3579"}
+{"ts": "2026-07-09T07:08:00Z", "file": "docs/self-docs/OPERATIONS.md", "change": "created", "from_hash": null, "to_hash": "878b50d02339acb7"}

data/docs/self-docs/COMPLIANCE.md

@@ -0,0 +1,79 @@
+---
+schema_version: "1.1"
+repo: "ecoportal-api-graphql"
+doc: compliance
+last_generated: "2026-07-09"
+source_head: "3f7b877"
+review_status: draft   # audit answers MUST come from 'reviewed' docs only -- a human sets this
+---
+
+# Compliance -- ecoportal-api-graphql
+
+**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.
+
+> This document is DRAFT and was composed from the repo's own context (CLAUDE.md, the
+> `.ai-assistance/code/` specs, and the active project INTENT). Fields marked PLANNED or "human to
+> confirm" MUST be verified by the repo owner before any audit use.
+
+## ISO 27001
+
+This is a Ruby client library (a gem), not a hosted service; it holds no infrastructure of its own and
+introduces no independent ISO-27001 control surface. Its compliance posture is inherited from (a) the
+ecoPortal platform it authenticates against and (b) the consuming project's runtime environment. The
+control this repo DOES own is access-scoping of the automation that uses it.
+
+| Control area | Status (evidence / planned) | Evidence link |
+|---|---|---|
+| Access control / least privilege (A.9) | EVIDENCE: the template-automation work is required to run under a per-org SERVICE ACCOUNT scoped to templates/org-config only, with page records structurally out of scope by credential grant (ep-ai-standards `security/ai-service-account-scope`). | `.ai-assistance/projects/template-automatic-build-maintenance/INTENT.md`; `security/ai-service-account-scope` standard |
+| Change control (A.12.1) | EVIDENCE: no silent breaking changes -- public-interface changes are recorded in the active project's DECISIONS log and confirmed with the developer; semver + CHANGELOG. | `CLAUDE.md`; `CHANGELOG.md` |
+| Input validation (A.14.2) | EVIDENCE: `no_schema: true` disables build-time schema validation; the compensating control is a query validator now covering mutations. | `.ai-assistance/code/` (query validator); `ARCHITECTURE.md` |
+| Auditability of automated changes | PLANNED / human to confirm: template BUILD/diff emits an ordered `WorkflowCommand` batch and a pairing ledger; whether that stream is retained as an audit trail for re-certification needs owner confirmation. | `.ai-assistance/code/diff_pairing_engine.md` |
+
+## Data handled
+
+The gem can read and write live ecoPortal domain objects through the API. Data classification is by
+CAPABILITY (what the client can touch), then narrowed by the credential scope in use at runtime.
+
+| Data class (none/team/customer/PII) | What / where | Treatment + retention | Exposed? (how) |
+|---|---|---|---|
+| Customer data + PII | Page records read/written via the GraphQL API (can contain personal data). | In-memory only during a client session; the gem persists nothing itself. Retention lives in the ecoPortal platform, not here. | Not exposed by the gem beyond the authenticated API call. Read/write capability is gated by the runtime credential; template-automation deliberately excludes page records by service-account scope. |
+| Customer/org config (non-PII) | Templates, location structures, org configuration. | In-memory during a session; changes applied via `WorkflowCommand` batches. Retention in the platform. | Only via the authenticated API; this is the scope the template-automation service account is limited to. |
+| Team-only | `.env` credentials for live tests (`ANTHROPIC_API_KEY`, ecoPortal creds via dotenv). | Local `.env`, gitignored; loaded only for `--tag live` specs. | Not committed; not exposed. |
+
+## Third-party vendors in the data path
+
+| Vendor | What data | Disclosed to end users? | Notes |
+|---|---|---|---|
+| Anthropic (Claude) | Only for `--tag live` AI tests, gated by `ANTHROPIC_API_KEY`. No customer page data is sent as part of normal gem operation. | N/A -- development-time only, not a production data path. | Live AI tests are opt-in; the gem's runtime API client does not call any LLM. Human to confirm no PII appears in live-test fixtures. |
+
+No customer/PII data leaves the ecoPortal boundary through this gem in normal operation: it is a client
+for ecoPortal's own API, not a bridge to an external SaaS.
+
+## PII / data-leak controls
+
+- **Credential scope (primary control):** the template-automation service account is scoped to
+  templates/org-config only, so page records (customer data + PII) are out of reach by GRANT, not by
+  instruction (ep-ai-standards `security/ai-service-account-scope`). This is the load-bearing leak
+  control.
+- **`org_id` scoping:** every client session is bound to a single org context; cross-org reads require
+  distinct credentials.
+- **No local persistence:** the gem holds data in memory for the session and writes nothing to disk;
+  there is no cache or log of customer records to leak.
+- **`.env` gitignored:** credentials for live tests never enter version control.
+- **Query validator:** compensates for `no_schema: true` by catching malformed queries/mutations before
+  they hit the live API.
+
+## AI-generated content
+
+- Externally-exposed AI content: **no.** The gem produces no customer-facing or publicly-exposed AI
+  content. AI assistance is confined to development (code generation, template-automation planning) and
+  `--tag live` AI tests; its output is reviewed code and internal artefacts, not exposed to end users.
+- Marked as AI-generated: **N/A** for external content. Internally, AI-assisted commits follow the
+  developer-only authorship convention (no `Co-Authored-By` unless requested), and Gemini responses must
+  be verified against actual code before applying.
+- Review process: standard MR review; public-interface changes additionally logged in the active
+  project's DECISIONS log and confirmed with the developer.