ecoportal-api-graphql 1.3.11 → 1.3.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78e2adbcdb62b6d2fdbf2ddb5906d9d8b5b93464af6269936b7eeda2dc94cb17
-  data.tar.gz: e6c55777dab78795abe7b81f419275cb52ec82a986aa92ee0da4affa4d5ca7e8
+  metadata.gz: 74b442ca224440bee94f3f88522a4233b995d187db1b70ba31a0801e0691d3eb
+  data.tar.gz: 5d5d05fdf46fac5a32a12c5d4c8e47c21b913332bbe04c40a3ab81beeacbab9a
 SHA512:
-  metadata.gz: 2bff88bcf06b31025a011fdb2b7d5f4a209aaa92b21c4c6c09ef1439da39a0b1e76fe75a204e5d4bc3e55dda5b7d4d6b215554650007b6d5097afa388ca08537
-  data.tar.gz: 0df6a4578b1ddbefa765f813fd97efd5f8e55fc84ad0384a7e7e6459f2ddc040dc6d8999af2493bb4e6368a638254ca7d8ed2154b7eae27bc40b965b80a94be4
+  metadata.gz: 7d667e7ed09fc6ed6fd200695567eb25a8bb5f4f41b3b98882e04d84acd1775c1a17dc7d424e82f26b7f89d4f826bb46c25fddc0ef5fc526e8731aaccd73193b
+  data.tar.gz: 324b54e96de9f7ae82e71bf1b2c0427fa6fd4ed99d0153ec836a85cf68d76d5ce8f8462865b29cddd446015caa2b4a5fcaf940c5c2866970d7814a2d0495a73b

data/.ai-assistance/code/filter_contract_matrix.md

@@ -0,0 +1,177 @@
+# Filter Contract Matrix — GraphQL register/page filters
+
+**Purpose.** Evidence-based ground-truth mapping of *ES register/page filter operations* to
+their exact params, per register field type, so the compat `FilterTranslator` can be validated
+against the backend rather than conjecture. Built after the Date/Select translator bug
+(commit e45ba58) where the original translation table was never validated.
+
+**Authoritative source.** `ecoPortal_master` Rails backend, `NewEp::Es` filter stack:
+
+- **Field-type → allowed operations** (the contract a register exposes):
+  `app/services/new_ep/es/definitions/page.rb`
+- **Operation → exact params** (constructor kwargs / `argument` declarations):
+  `app/services/new_ep/es/filters/pages/**` and `.../filters/global/**`
+- **Operation string → class dispatch:**
+  `app/services/new_ep/es/filters/deserializer.rb:51-58` — the `operation` string is
+  `camelize`d + suffixed `Filter`, resolved **first** under `NewEp::Es::Filters::Pages::`,
+  then falling back to `NewEp::Es::Filters::Global::`. An operation with no matching class
+  raises `UnknownFilterError` (`deserializer.rb:59`). This is why `options_filter` /
+  `text_filter` (v2 names) are NOT valid GraphQL operations — see §"v2 → GraphQL" below.
+
+All line numbers below are `file:line` in `ecoPortal_master` unless noted. GraphQL param names
+match the backend constructor / `argument` declarations exactly.
+
+---
+
+## 1. v2 → GraphQL translator input types (what `Compat::FilterTranslator` handles)
+
+`lib/ecoportal/api/graphql/compat/filter_translator.rb` accepts *v2-style* `type:` hashes and
+emits GraphQL `{operation:, params:}` hashes. The v2 `type` names are NOT backend operation
+names; the emitted `operation` names ARE. Every emitted operation below resolves to a real
+backend class (verified via the deserializer dispatch).
+
+| v2 `type` | Emitted GraphQL `operation` | Emitted params | Backend class (evidence) | Translator handles? |
+|---|---|---|---|---|
+| `date_filter` (system key, e.g. `created_at`) | `date_filter` | `key, time_zone, gte?(=lbound), lte?(=ubound)` | `Global::DateFilter` — `date_filter.rb:28` (`key, path, gt, gte, lt, lte`) | YES (`filter_translator.rb:110-124`) |
+| `date_filter` (field key, e.g. `date.zXXXX`) | `range_date_filter` | `key, path=membranes.date, time_zone, gte?, lte?` | `Pages::RangeDateFilter` — `range_date_filter.rb:797` (`key, path, gte, lte, gt, lt`) | YES (`filter_translator.rb:110-124`) |
+| `text_filter` | `match_filter` | `key, value(=query)` | `Global::MatchFilter` — `match_filter.rb:6` (`key, value, path`) | YES (`filter_translator.rb:74-82`) |
+| `exact_filter` / `is_filter` | `is_filter` | `key, path?(derived membranes.<type>), value` | `Pages::IsFilter` — `is_filter.rb:258` (`key, path, value`) | YES (`filter_translator.rb:52-57`) |
+| `options_filter` (system key) | `one_of_filter` / `none_of_filter` (exclude) | `key, values(=chosen)` | `Global::OneOfFilter` — `one_of_filter.rb:16` (`key, values`); `Global::NoneOfFilter` — `none_of_filter.rb:6` (`key, values`) | YES (`filter_translator.rb:90-104`) |
+| `options_filter` (field key, e.g. `select_str.zXXXX`) | `has_any_filter` / `doesnt_have_any_filter` (exclude) | `key, path(=membranes.<type>), field_key='selected', values(=chosen)` | `Pages::HasAnyFilter` — `has_any_filter.rb:995` → `Pages::BaseHasAnyFilter` — `base_has_any_filter.rb:10` (`key, path, field_key, values, invert`); `Pages::DoesntHaveAnyFilter` — `doesnt_have_any_filter.rb:1061` | YES (`filter_translator.rb:90-104`) |
+| `tag_filter` | *(passthrough — no rewrite)* | — | n/a (already GraphQL-shaped) | passthrough (`filter_translator.rb:37-39`) |
+| `register_filter` | *(passthrough)* | — | `Pages::RegisterFilter` (`filters/pages/register_filter.rb`) | passthrough |
+| `and_filter` / `or_filter` | *(passthrough)* | — | `Global::AndFilter` / `Global::OrFilter` | passthrough |
+| already-`{operation:,params:}` hash | *(passthrough)* | — | — | passthrough (unmatched `type`) |
+| SearchConf value object (`to_h`, not Hash) | *(passthrough)* | — | — | passthrough (`filter_translator.rb:25`) |
+
+### Why `options_filter` / `text_filter` are NOT emitted verbatim
+
+- **`options_filter`**: there is NO `Pages::OptionsFilter` or `Global::OptionsFilter` class.
+  The closest backend class is `Pages::OptionsFieldFilter` (op `options_field_filter`,
+  `options_field_filter.rb:9`, takes `chosen`/`mode`) — a *different* operation the register
+  definitions never expose. Emitting `options_filter` verbatim would raise `UnknownFilterError`.
+  So the translator rewrites to the backend-blessed `has_any_filter`/`one_of_filter`.
+- **`text_filter`**: a `Pages::TextFilter` class DOES exist (`text_filter.rb:1252`) but its
+  constructor takes `key:, query:` (not `value:`) and register definitions never expose a
+  `text_filter` operation — they expose `contains_filter`/`is_filter`. The translator therefore
+  emits `match_filter` (`Global::MatchFilter`, `match_filter.rb:6`), which is a valid operation
+  with `{key, value}`. NOTE: `match_filter` matches the *analyzed* value (partial/full-text);
+  for whole-value exact use `is_filter` (see §exact-vs-partial in `search_filters.md`).
+
+---
+
+## 2. Field-type contract matrix (register/page fields)
+
+One row per **(field type, operation)** enumerated from `page.rb`. `key` = field definition key
+(`<type>.zXXXX`); `path` = the nested membranes path the definition hardcodes. `field_key` /
+`values` shown where the operation carries a subfield. "Translator?" marks whether the compat
+`FilterTranslator` currently produces this operation from a v2 input.
+
+### 2.1 System / metadata fields (no `membranes.*` path)
+
+| Field | v2 type | GraphQL operation(s) | params | page.rb evidence | Translator? |
+|---|---|---|---|---|---|
+| Created on / Updated on | `date_filter` | `date_filter`, `isnt_in_date_filter` | `key=created_at`, gte/lte/time_zone | `page.rb:31-39` | YES (system date branch) |
+| External ID | `exact_filter` | `is_filter`, `isnt_filter`, `is_empty_filter`, `isnt_empty_filter` | `key=external_id`, value | `page.rb:65-70` | YES via `exact_filter`→`is_filter` (no path — system key) |
+| Page ID (`mould_counter`) | — | `is_filter`, `isnt_filter`, `is_empty_filter`, `isnt_empty_filter`, `contains_filter`, `doesnt_contain_filter` | `key=mould_counter`, value | `page.rb:72-79` | is_filter YES; contains_filter NO |
+| Page name (`name`) | `text_filter`/`exact_filter` | `is_filter`, `isnt_filter`, `contains_filter`, `doesnt_contain_filter` | `key=name`, value | `page.rb:81-86` | is_filter YES; match/contains partial: `text_filter`→`match_filter` (valid but `name` uses QueryFilter internally — see NOTE) |
+| Page status (`state`) | `options_filter`/`exact` | `is_filter`, `isnt_filter` | `key=state`, value(`@extras`) | `page.rb:87-99` | via `exact_filter`→`is_filter` YES |
+| System ID (`id`) | `exact_filter` | `is_filter`, `isnt_filter`, `one_of_filter` | `key=id`, value / values | `page.rb:101-105` | is_filter + one_of_filter YES |
+| Assigned to | — | `is_filter`, `isnt_filter`, `has_all/any_filter`, `doesnt_have_all/any_filter` | `key=assigned_to`, field_key=`assigned_to`, values | `page.rb:15-22` | NO (no v2 driver) |
+| Created by | — | `is_filter`, `isnt_filter`, `has_any_filter`, `doesnt_have_any_filter` | `key=creator_id`, field_key=`creator_id` | `page.rb:24-29` | NO |
+| Created via (`source`) | — | `is_filter`, `isnt_filter` | `key=source`, value | `page.rb:41-45` | via is_filter YES (if driven) |
+| Custom tags (`other_tags`) | `tag_filter` | `has_any/all_filter`, `doesnt_have_any/all_filter`, `is_empty_filter`, `isnt_empty_filter` | `key=other_tags`, field_key=`other_tags`, values | `page.rb:56-63` | passthrough (`tag_filter`) |
+| Tags / locations (`all_location_ids`) | `tag_filter` | `has_any/all_filter`, `doesnt_have_any/all_filter`, `is_empty_filter`, `isnt_empty_filter` | `key=all_location_ids`, field_key=`all_location_ids`, values | `page.rb:107-114` | passthrough (values lowercased backend-side: `has_any_filter.rb:1024`) |
+| Current Stage (`active_stage_names`) | — | `has_any/all_filter`, `doesnt_have_any/all_filter` | `key=active_stage_names`, field_key=`active_stage_names`, values | `page.rb:138-143` | NO |
+
+NOTE (`name`): `contains_filter` on `name` routes to `Global::MatchFilter` (`contains_filter.rb:453-455`)
+and `is_filter` on `name` routes to `Global::ExactFilter` on `name.exact` (`is_filter.rb:283-284`).
+The translator's `text_filter`→`match_filter{key:'name',value:}` therefore hits the right backend
+class for partial name search.
+
+### 2.2 Register data fields (nested `membranes.<type>` path)
+
+| Field type | GraphQL operation(s) | params (key/path/field_key/values) | page.rb evidence | Backend op class | Translator? |
+|---|---|---|---|---|---|
+| **date** (`date.zXXXX`) | `range_date_filter`, `isnt_in_range_date_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.date`; range: gte/lte/gt/lt/time_zone | `page.rb:191-209` | `Pages::RangeDateFilter` `range_date_filter.rb:797`; field_key resolved to `value` `range_date_filter.rb:822-828` | YES (`date_filter` field branch → `range_date_filter`) |
+| **select_str** (`select_str.zXXXX`) | `has_any/all_filter`, `doesnt_have_any/all_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.select_str`, field_key=`selected`, values | `page.rb:279-300` | `Pages::HasAnyFilter`→`BaseHasAnyFilter` `base_has_any_filter.rb:10`; search_key=`path.selected` `base_has_any_filter.rb:42-44` | YES (`options_filter` field branch → `has_any_filter`) |
+| **select_num** (`select_num.zXXXX`) | same as select_str, path=`membranes.select_num` | key, path, field_key=`selected`, values | `page.rb:256-277` | `Pages::HasAnyFilter`→`BaseHasAnyFilter` | YES (field branch; caller passes path/`select_num` prefix) |
+| **plain_text** (`plain_text.zXXXX`) | `is_filter`, `isnt_filter`, `is_empty_filter`, `isnt_empty_filter`, `contains_filter`, `doesnt_contain_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.plain_text`; is_filter → `.exact` subfield | `page.rb:145-165` | `is_filter`→`Pages::IsFilter`→`BaseIsFilter` search_key=`exact` `is_filter.rb:315-316`; contains→`Pages::TextFilter` `contains_filter.rb:459-461` | is_filter YES (exact_filter→is_filter); contains NO |
+| **rich_text** (`rich_text.zXXXX`) | `contains_filter`, `doesnt_contain_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.rich_text`; contains → `content` subfield | `page.rb:303-321` | `contains_filter`→`BaseContainsFilter` field_key=`content` `contains_filter.rb:477-478` | NO (no is/exact op; contains only) |
+| **number** (`number.zXXXX`) | `numeric_range_filter`, `isnt_in_numeric_range_filter`, `is_filter`, `isnt_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.number`; range: gte/lte/gt/lt on `.value` | `page.rb:168-188` | `numeric_range_filter`→`Pages::NumericRangeFilter` search_key=`path.value` `numeric_range_filter.rb:941-943` | is_filter YES; numeric_range NO |
+| **gauge** (`gauge.zXXXX`) | `is_filter`, `isnt_filter`, `numeric_range_filter`, `isnt_in_numeric_range_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.gauge` | `page.rb:234-254` | numeric via `NumericRangeFilter`; is via `IsFilter` search_key=`value` `is_filter.rb:317-318` | is_filter YES; numeric_range NO |
+| **file** (`file.zXXXX`) | `has_any_filter`, `doesnt_have_any_filter` (×`file_container_id`, `content_type`), `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.file`, field_key=`file_container_id`\|`content_type`, values | `page.rb:212-232` | `has_any_filter`→`Pages::File::HasAnyFilter` `has_any_filter.rb:1034-1035` | NO |
+| **image_gallery** (`image_gallery.zXXXX`) | `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.image_gallery` | `page.rb:545-561` | `is_empty`→`Pages::ImageGallery::IsEmptyFilter` `is_empty_filter.rb:572-573` | NO |
+| **people** (`people.zXXXX`) | `has_any/all_filter`, `doesnt_have_any/all_filter` (×`id`/`contractor_organization_id`/`schema_id`/`prefilter_location_ids`), `is_direct_supervisor_filter`, `has_direct_supervisor_filter`, `is/isnt_contractor_administrator_filter`, `people_field_contains_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.people`, field_key varies, values | `page.rb:466-499` | `Pages::People::HasAnyFilter` `has_any_filter.rb:1030-1031` | NO |
+| **contractor_entities** (`contractor_entities.zXXXX`) | `has_any/all_filter`, `doesnt_have_any/all_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.contractor_entities`, field_key=`contractor_entities_ids`, values | `page.rb:324-344` | `BaseHasAnyFilter`; `required_data` loads ContractorEntity `base_has_any_filter.rb:27-28` | NO |
+| **cross_reference / page_reference** (`cross_reference.zXXXX`, `any_reference_field`) | `has_any_filter`, `doesnt_have_any_filter`, `has_all_filter`, `doesnt_have_all_filter`, `meets_conditions_filter`(if CRR), `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.cross_references`, field_key=`id`, values=`@page_id`; meets_conditions: `register_id` | `page.rb:502-542` | `Pages::CrossReferences::HasAnyFilter` `has_any_filter.rb:1021-1022` | NO |
+| **actions_list** (`actions_list.zXXXX`) | `has_any/all_filter`, `doesnt_have_any/all_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.actions_list`, field_key=`id`, values=`@action_id` | `page.rb:347-367` | `Pages::ActionsList::HasAnyFilter` `has_any_filter.rb:1032-1033` | NO |
+| **checklist** (`checklist.zXXXX`) | `all_options_ticked_filter`, `not_all_options_ticked_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.checklist` | `page.rb:445-463` | `all_options_ticked_filter` = `Pages::AllOptionsTickedFilter` (`all_options_ticked_filter.rb`) | NO |
+| **geo** (`geo.zXXXX`) | `is_filter`, `isnt_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.geo`; is → `address.exact` subfield | `page.rb:370-388` | `IsFilter` search_key=`address.exact` `is_filter.rb:319-320` | is_filter YES (if driven); rest NO |
+| **signature** (`signature.zXXXX`) | `is_filter`, `isnt_filter` (value=`@user_id`), `range_date_filter`, `isnt_in_range_date_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.signature`; is → `signed_by_id`; range → `date` subfield | `page.rb:391-411` | `IsFilter` search_key=`signed_by_id` `is_filter.rb:323-324`; range → `Pages::Signature::RangeDateFilter` `range_date_filter.rb:810-811` | is_filter/range partial (translator emits generic ops; subfield resolution is backend-side by key prefix) |
+| **mailbox** (`mailbox.zXXXX`) | `range_date_filter`, `isnt_in_range_date_filter`, `has_any/all_filter`, `doesnt_have_any/all_filter` (×`all_recipients`/`sender_email`), `contains_filter`, `doesnt_contain_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.mailbox`, field_key varies, values | `page.rb:414-442` | `Pages::Mailbox::*` `has_any_filter.rb:1019-1020` | NO |
+| **law** (`law.zXXXX`) | `has_any_filter`, `doesnt_have_any_filter`, `is_empty_filter`, `isnt_empty_filter`, `presence_filter`, `not_presence_filter` | key, path=`membranes.law`, field_key=`snippets_ids`, values=`@law_snippet_id` | `page.rb:564-582` | `BaseHasAnyFilter`; `required_data` loads Snippet `base_has_any_filter.rb:29` | NO |
+
+---
+
+## 3. Operation → param contract (backend constructor signatures)
+
+Cited so the guard spec asserts exact param shapes. All under
+`app/services/new_ep/es/filters/`.
+
+| Operation | Namespace / class | Constructor params (evidence) |
+|---|---|---|
+| `date_filter` | `Global::DateFilter` | `key, path?, gt?, gte?, lt?, lte?` — `global/date_filter.rb:28` |
+| `range_date_filter` | `Pages::RangeDateFilter` | `key, path?, gte?, lte?, gt?, lt?` — `pages/range_date_filter.rb:797` |
+| `is_filter` | `Pages::IsFilter` | `key, path?, value?` — `pages/is_filter.rb:258` |
+| `isnt_filter` | `Pages::IsntFilter` | `key, path?, value` — `pages/isnt_filter.rb:360` |
+| `match_filter` | `Global::MatchFilter` | `key, value, path?` — `global/match_filter.rb:6` |
+| `contains_filter` | `Pages::ContainsFilter` | `key, path?, value` — `pages/contains_filter.rb:445` |
+| `has_any_filter` | `Pages::HasAnyFilter` → `BaseHasAnyFilter` | `key, path?, field_key?, values` — `pages/has_any_filter.rb:995`, `pages/base_has_any_filter.rb:10` |
+| `has_all_filter` | `Pages::HasAllFilter` → `BaseHasAllFilter` | `key, path?, field_key?, values` — `pages/has_all_filter.rb:1135`, `pages/base_has_all_filter.rb:59` |
+| `doesnt_have_any_filter` | `Pages::DoesntHaveAnyFilter` | `key, path?, field_key?, values` (invert) — `pages/doesnt_have_any_filter.rb:1061` |
+| `doesnt_have_all_filter` | `Pages::DoesntHaveAllFilter` | `key, path?, field_key?, values` (invert) — `pages/doesnt_have_all_filter.rb:1199` |
+| `one_of_filter` | `Global::OneOfFilter` | `key, values` — `global/one_of_filter.rb:16` |
+| `none_of_filter` | `Global::NoneOfFilter` | `key, values` — `global/none_of_filter.rb:6` |
+| `numeric_range_filter` | `Pages::NumericRangeFilter` | `key, path?, gte?, lte?, gt?, lt?` — `pages/numeric_range_filter.rb:917` |
+| `is_empty_filter` | `Pages::IsEmptyFilter` | `key, path?` (search_key by type) — `pages/is_empty_filter.rb:552` |
+| `presence_filter` | `Pages::PresenceFilter` | `key, path?` — `pages/presence_filter.rb:724` |
+
+---
+
+## 4. Known-UNCOVERED field types / operations (visible gap, not silent)
+
+The compat `FilterTranslator` intentionally translates only the v2 filter shapes that real
+consumers emit (`date_filter`, `text_filter`, `exact_filter`/`is_filter`, `options_filter`,
+plus passthroughs). The following register field types / operations have a backend contract
+(cataloged above) but NO translator branch. This is by design — do not add speculative
+translations without a consumer. The guard spec enumerates these so the gap stays visible.
+
+**Field types with NO dedicated translator path** (any v2 filter targeting them falls through
+to passthrough — the caller must pass a pre-shaped `{operation:,params:}` hash):
+
+- `number` (numeric_range_filter), `gauge` (numeric_range_filter)
+- `rich_text` (contains_filter / doesnt_contain_filter)
+- `file` (has_any_filter on file_container_id / content_type)
+- `image_gallery` (is_empty / presence only)
+- `people`, `contractor_entities`, `cross_reference` / `page_reference`
+- `actions_list`, `checklist`, `mailbox`, `law`, `signature` (range/is subfields)
+- `geo` (is_filter on address.exact — reachable via exact_filter if the caller sets key `geo.zXXXX`)
+
+**System fields with NO translator driver:** `assigned_to`, `creator_id` (Created by),
+`active_stage_names` (Current Stage), `mould_counter` contains_filter.
+
+**Operations never emitted by the translator** (must be passed pre-shaped): `has_all_filter`,
+`doesnt_have_all_filter`, `numeric_range_filter`, `isnt_in_numeric_range_filter`,
+`isnt_in_range_date_filter`, `contains_filter`, `doesnt_contain_filter`, `is_empty_filter`,
+`isnt_empty_filter`, `presence_filter`, `not_presence_filter`, `meets_conditions_filter`,
+`all_options_ticked_filter`, `people_field_contains_filter`, direct-supervisor / contractor-admin
+filters.
+
+---
+
+## 5. Change log
+
+- 2026-07-08 — Initial matrix built from `page.rb` + `filters/pages/**` + `filters/global/**`.
+  Guard spec `spec/ecoportal/api/graphql/compat/filter_translator_spec.rb` extended to pin every
+  emitted operation to its backend param contract and to enumerate the uncovered types.

data/.ai-assistance/projects/template-automatic-build-maintenance/INTENT.md

@@ -4,6 +4,16 @@
 `template-diff-deploy` + `template-maintenance` projects into one plan).
 **Domain reference (read first):** `.ai-assistance/code/template_diff_pairing_domain.md`
 **Code spec:** `.ai-assistance/code/diff_pairing_engine.md`
+**Governing security standard (read before wiring live creds):** `security/ai-service-account-scope`
+in ep-ai-standards. This automation MUST authenticate as a dedicated per-org SERVICE ACCOUNT whose
+grant covers templates/org-config only -- page records (customer data + PII) are structurally out of
+scope, enforced by the credential grant, not by instruction. This is the practitioner discovery point
+for that standard (the template automation is its concrete consumer). The "sandbox creds" in success
+criterion #4 below must be provisioned to that scope. Platform dependency RESOLVED: templates ARE pages
+(`PageUnion`), but `stage.tags` (wrongly deprecated ~21 months ago) has been restored via ecoPortal MR
+!6649, so a rule scoped to template stages can structurally exclude record stages. Defining and
+provisioning the concrete grant is now OUR work (this gem + agent), not a platform blocker -- see the
+service-account grant task in `TODO.md`.
 **Superseded folders (pointers only now):** `template-diff-deploy/`, `template-maintenance/`.
 **Sibling projects:** `qa-services-delivery` (verify), `ooze-graphql-native-migration`,
 `template-csv-pipeline` (memory).

data/.ai-assistance/projects/template-automatic-build-maintenance/TODO.md

@@ -90,6 +90,17 @@ emission layer: an ordered `WorkflowCommand` batch with `placeholderId` threadin
 ---
 
 ## Cross-cutting
+- [ ] **Service-account grant (gates live use; governed by ep-ai-standards `security/ai-service-account-scope`).**
+  This automation must run as a dedicated per-org SERVICE ACCOUNT scoped to templates/org-config only --
+  page records out of scope, enforced by the grant (structural PII/compliance boundary, not instruction).
+  Platform enabler is in place: `stage.tags` (wrongly deprecated ~21 months ago) restored via ecoPortal
+  MR !6649, so a rule scoped to template stages can exclude record stages. OUR remaining work:
+  (a) enumerate in-scope object types (templates; and which of registers / stages / tag defs / workflow +
+  automation config / custom-field defs -- explicit in/out per type, each a potential path back to records);
+  (b) write the concrete `stage.tags` rule and confirm no record stage shares those tags;
+  (c) fix the read/write surface per type (edit templates? read-only org-config?);
+  (d) provision the per-org account and confirm its `canXXX` set carries NO page-record capability.
+  Feeds the "sandbox creds" needed by Phase B2 / Phase 5. Reference: INTENT header + the standard.
 - [ ] Tighten `ecoportal-qa` to consume the gem's page-model instead of its own `TemplateModel`.
 - [ ] Emit `stageId`/`sectionId` back-refs on diff-side `addField`/`addSection` (BUILD already does;
   the diff synthesizer's structural adds still emit only label/placeholder — then threading covers them).

data/.ai-assistance/skills/procedural-memory/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: procedural-memory
+category: governance
+version: 0.2.0
+status: draft
+description: >
+  Distills accumulated session signals into stored `procedural` memory entries
+  (recurring routines: a trigger condition + the action that reliably follows) and
+  surfaces them as likely next steps. Invoke on a periodic distill pass or when a
+  developer asks what patterns you have noticed in how they work.
+triggers:
+  - what patterns have you noticed
+  - distill my routines
+  - procedural memory
+  - how do I work
+  - learn my routines
+  - weekly distill
+  - modus operandi
+applicable_to:
+  - any
+---
+
+# procedural-memory
+
+## Purpose
+
+Turn the substrate of accumulated session history into stored **`procedural`** memory --
+recurring routines, each expressed as a **trigger condition** and the **inferred action**
+that reliably follows it -- and surface those routines (plus a short "likely next steps"
+list) so the next session starts proactively shaped instead of from scratch.
+
+This skill operationalizes the **Distill** stage of the Observe -> Distill -> Act loop, plus
+the human-facing part of the **Act** stage (surfacing). It implements
+`standards/workflows/procedural-memory.md`. Observation (the `Stop`/`SessionEnd` logging
+substrate) and autonomous execution (the auto-worker) are out of scope here -- this skill
+reads the Observe substrate and writes the inferred routines; it never acts on them itself.
+
+> **v0.2.0 -- draft-aligned, blockers resolved.** This skill tracks
+> `standards/workflows/procedural-memory.md` at v0.2.0 (`status: draft`, ready for consolidation
+> review). It implements the now-decided **decay/retirement lifecycle** (D1) and **Observe-stage
+> privacy policy** (D2). The distill cadence, the minimum-observation threshold, the promotion
+> rule, and the lifecycle numbers (confidence steps, retirement floor, staleness/cool-off
+> windows) are all **provisional** and will firm up when the standard reaches `status: reviewed`.
+> Treat the numbers below as conservative defaults, not settled policy.
+
+---
+
+## When to invoke
+
+- **On a periodic distill pass** -- e.g. weekly, or as part of an end-of-week wrap-up. This is
+  the primary mode: a scheduled mining pass over accumulated session history.
+- **On demand** -- when a developer asks "what patterns have you noticed in how I work?",
+  "distill my routines", or similar. Run the same procedure, scoped to the data available.
+
+Do not invoke this skill to *perform* a routine -- it only distils and surfaces. Acting on a
+surfaced routine is gated separately (see HARD CONSTRAINTS).
+
+---
+
+## On invocation
+
+Before any other output, do both of the following:
+
+1. Print to the user:
+   `[skill: procedural-memory] <one-line description of what you are about to do>`
+   Examples:
+   - Periodic pass: `[skill: procedural-memory] weekly distill — mining usage log for recurring routines`
+   - On demand: `[skill: procedural-memory] reviewing session history for patterns in how you work`
+
+2. Append a usage record to `.ai-assistance/local/kpi/usage-<YYYY-WNN>.jsonl`
+   (ISO week format, e.g. `2026-W26`):
+   ```json
+   {"component": "skill/procedural-memory", "action": "invoked", "detail": "<same one-liner>", "ts": "<ISO timestamp>", "session_id": "<if known>"}
+   ```
+   Before writing, run the scrub/redaction pass (see Privacy below) over the record. If the file
+   or directory does not exist, create it. If writing fails, continue silently.
+
+### Consent check (do this first)
+
+The Observe log is **opt-in**. Before reading any `usage-*.jsonl` to mine routines, confirm the
+developer has enabled Observe (`procedural_memory.observe: true` in local settings, or the
+equivalent Observe-hook entry). If consent is not set, report that the Observe stage is not
+enabled, do NOT read the log, and stop. (Writing this skill's own invoked/completed usage
+records is the skill announcing itself and is unaffected by the Observe consent flag.)
+
+---
+
+## The procedure
+
+### Step 1 -- Read the Observe substrate
+
+The Observe stage is append-only and machine-local; this skill only reads it. Read only after
+the consent check above has passed.
+
+- Read `.ai-assistance/local/kpi/usage-<YYYY-WNN>.jsonl` across the distill window (default: the
+  current and previous 3 ISO weeks). These records carry only low-sensitivity signal: command/
+  tool names (not arguments), file paths/types touched, components invoked, event types and
+  `action` values, and coarse durations/counts -- never full arguments, file contents, or
+  prompt/response text (see Privacy below). Parse defensively: skip malformed/corrupt JSON lines
+  rather than failing the whole pass.
+- Optionally read `docs/worklog.md` for `<!-- LEARNING: ... -->` markers. These are the
+  human-authored analogue of a `procedural` entry and may seed the distill pass
+  (`standards/workflows/session-handoff.md`).
+
+If no usage log exists, report that the Observe substrate is not yet populated and stop --
+there is nothing to distil. Do not invent routines from a single session.
+
+### Step 2 -- Mine for recurring patterns
+
+A pattern is a **trigger condition** plus the **action that reliably follows it** within the
+same or the next session. Look for:
+
+- An action that consistently follows a specific event (e.g. a code-spec regeneration that
+  follows every merge to `main`).
+- A consistent ordering of actions (e.g. tests -> lint -> commit).
+- A deferral that is consistently picked up at a predictable later point.
+
+**Minimum-observation threshold.** A pattern is only written if it was **observed in >= 3
+distinct sessions** in the window. This default is deliberately conservative to stop a one-off
+coincidence becoming a stored routine; the standard leaves the exact number open, so treat
+this as **provisional**. Below threshold: note it as a *candidate* in the report, but do not
+write a memory entry.
+
+### Step 3 -- Write each confirmed pattern as a `procedural` memory entry
+
+Write each pattern at or above threshold into the repo-scoped memory directory
+`~/.claude/projects/<project>/memory/` (auto memory -- repo-scoped and machine-local), as a
+memory entry of **type `procedural`**. The body carries **Trigger:** and **Inferred action:**
+lines, mirroring how `feedback` entries use **Why:** / **How to apply:**:
+
+```markdown
+## [Short routine name]
+
+**Trigger:** [the observed condition that recurs]
+**Inferred action:** [what the developer reliably does next]
+**Confidence:** 0.6
+**First-observed:** [YYYY-MM-DD]
+**Last-observed:** [YYYY-MM-DD]
+
+Observed in X of Y opportunities across N sessions (source: usage-<YYYY-WNN> ... usage-<YYYY-WNN>).
+```
+
+New entries start at **Confidence: 0.6** (provisional) -- above the retirement floor, below full
+trust, so a freshly inferred routine starts on probation. **First-observed** and **Last-observed**
+are both set to the current distill-pass date on first write. These three lines are required: they
+drive the decay/retirement lifecycle in Step 3b.
+
+Then add the index pointer line to `~/.claude/projects/<project>/memory/MEMORY.md`, matching
+the existing index style:
+
+```markdown
+- [Procedural: <short routine name>](<filename>.md) — <one-line trigger → action summary>
+```
+
+Mark the entry clearly as `procedural` so it stays distinguishable from `user`/`project`
+memory (see HARD CONSTRAINTS).
+
+### Step 3b -- Re-evaluate, decay, and retire existing routines
+
+On every distill pass, before reporting, walk each existing `procedural` entry and update its
+lifecycle metadata (standard D1). Honour forced markers first, then apply the arithmetic.
+
+1. **Forced markers (one-shot, applied first).** Scan `docs/worklog.md` and the memory files for:
+   - `<!-- RETIRE: <short routine name> -->` -- retire that routine immediately (see step 4
+     below), regardless of confidence or recency.
+   - `<!-- CONFIRM: <short routine name> -->` -- set its **Confidence** to `1.0` and refresh
+     **Last-observed** to today.
+   Record that the marker was applied so it is not re-applied on the next pass.
+
+2. **Re-evaluate against this window.** For each routine whose **Trigger** occurred at least once
+   in the window:
+   - trigger fired AND inferred action followed: refresh **Last-observed** to today and
+     **increment Confidence by +0.1**, capped at `1.0`;
+   - trigger fired but action did NOT follow: **decrement Confidence by -0.2** (contradiction
+     costs more than a single confirmation earns -- intentional asymmetry);
+   - trigger did not fire at all: leave Confidence unchanged; do NOT refresh Last-observed.
+
+3. **Retire** a routine when EITHER its **Confidence < 0.3** (floor) OR its **Last-observed** is
+   **older than 90 days** (staleness window). All thresholds provisional.
+
+4. **Archive on retirement -- never silent-delete.** Move the entry file to
+   `~/.claude/projects/<project>/memory/retired/`, appending the retirement date and reason
+   (`confidence floor` / `staleness` / `forced`). Remove its line from `MEMORY.md`. Keep a
+   tombstone (routine name + retirement date + reason). When mining (Step 2), if a re-detected
+   Trigger/Inferred-action pair matches a tombstone retired **within the last 30 days**
+   (cool-off, provisional), do NOT auto-write it -- surface it as a *candidate* for the developer
+   to re-confirm. After the cool-off it may be written fresh at the initial confidence.
+
+### Step 4 -- Promotion (propose only)
+
+A routine observed consistently **across multiple repos** is a candidate cross-project trait
+for user-global memory in `~/.claude/CLAUDE.md`. **Propose it -- do not auto-promote.** Present
+the candidate and the evidence; the developer decides. The exact promotion threshold is an
+open question in the standard and is provisional here.
+
+### Step 5 -- Act / surface
+
+Present the result to the developer:
+
+1. The distilled routines (newly written and pre-existing) for this repo.
+2. A short **"likely next steps"** list inferred from the current state and the routines.
+3. For routines whose inferred action is mechanically actionable, **PROPOSE** (never auto-add)
+   an `[auto]` tag so the auto-worker could pre-stage it -- subject to the developer confirming
+   the tag. The `[auto]` tag is the authorization boundary; eligibility rules in
+   `standards/tooling/auto-worker-eligibility.md` still apply, and this skill never tags
+   anything itself.
+
+After surfacing, append a completion usage record:
+```json
+{"component": "skill/procedural-memory", "action": "completed", "detail": "<N routines written, M candidates, K promotions proposed>", "ts": "<ISO timestamp>", "session_id": "<if known>"}
+```
+
+---
+
+## HARD CONSTRAINTS
+
+From `standards/workflows/procedural-memory.md` -- these are not optional:
+
+- **A `procedural` entry is an inference, not an asserted fact.** It must remain visibly
+  distinguishable from `user`/`project` memory (which record things the developer stated), so
+  a wrong inference can be retired without eroding trust in asserted facts.
+- **Suggest, never act.** A distilled routine may *suggest* a next step or an `[auto]` tag, but
+  it must not drive an autonomous action without a human-in-the-loop confirmation. Any routine
+  that would trigger an irreversible or shared-system action is subject to
+  `standards/workflows/hitl-gates.md` -- inference grants no authority to act.
+- **Observe logging is opt-in, scrubbed, and machine-local (standard D2).** The Observe hook is
+  off by default; do not read the usage log to mine routines unless consent is set (see Consent
+  check). Capture only the documented allow-list -- command/tool names, file paths/types, event
+  types, durations -- and NEVER full arguments, file contents, diffs, or prompt/response text.
+  Run the scrub/redaction pass (regex for tokens/keys, emails, obvious PII; replace with typed
+  placeholders; drop a record that cannot be confidently scrubbed) BEFORE writing any record.
+  Never copy the log off the machine, into a versioned file, or into a `procedural`/promoted
+  entry -- entries store only the distilled Trigger/Inferred-action plus aggregate evidence.
+- **Decay and retirement are mandatory (standard D1).** Every `procedural` entry carries
+  **Confidence**, **First-observed**, and **Last-observed**. Each pass re-evaluates them, retires
+  entries below the floor or past the staleness window, honours `<!-- RETIRE: -->` /
+  `<!-- CONFIRM: -->` markers, and archives (never silently deletes) retired entries with a
+  cool-off tombstone so a retired routine does not silently reappear.
+- **Repo-relative paths only** in any versioned output. Use `~/.claude/...` solely as the
+  canonical memory location, never a developer's absolute filesystem path.
+
+### Privacy -- what the Observe log captures, redacts, and where it lives
+
+- **Captured:** command/tool names; file paths/types touched (repo-relative); event types and
+  `action` values; coarse durations and counts; timestamps, ISO-week, session id.
+- **Never captured:** full command arguments; file contents or diffs; prompt/response text; the
+  literal text of corrections/redirects (only that one occurred, and its coarse type); secrets,
+  tokens, credentials, env values.
+- **Redaction:** scrub-before-write -- regex detectors for tokens/keys (high-entropy strings,
+  `sk-`/`ghp_`/AWS-style prefixes), emails, obvious PII; matches replaced with `<REDACTED:...>`;
+  unscrubabble records dropped.
+- **Storage/consent:** lives only at `.ai-assistance/local/kpi/usage-<YYYY-WNN>.jsonl`
+  (machine-local, gitignored, never committed). Enable via `procedural_memory.observe: true` in
+  local settings; disable by removing it; the developer may delete the log at any time.
+
+---
+
+## Example -- one mined pattern -> resulting `procedural` entry
+
+**Observed.** Over four ISO weeks the usage log shows that in 4 of 4 sessions ending with a
+merge to `main`, the same or next session regenerates code-specs and bumps the changelog
+before any new branch is opened. 4 sessions >= the threshold of 3, so it is written.
+
+Resulting file `~/.claude/projects/<project>/memory/procedural-merge-followup.md`:
+
+```markdown
+## Post-merge spec + changelog routine
+
+**Trigger:** a feature branch is merged to `main`.
+**Inferred action:** regenerate code-specs and bump the changelog before opening the next branch.
+**Confidence:** 0.6
+**First-observed:** 2026-06-28
+**Last-observed:** 2026-06-28
+
+Observed in 4 of 4 opportunities across 4 sessions (source: usage-2026-W22 ... usage-2026-W25).
+```
+
+On a later pass, if a merge to `main` is NOT followed by the spec+changelog action, Confidence
+drops by 0.2; sustained contradiction (or a `<!-- RETIRE: Post-merge spec + changelog routine -->`
+marker, or 90 days without observation) retires it to `memory/retired/`.
+
+Index line added to `MEMORY.md`:
+
+```markdown
+- [Procedural: Post-merge spec + changelog routine](procedural-merge-followup.md) — merge to main → regenerate code-specs + bump changelog
+```
+
+Surfaced at the next post-merge session as a likely next step, with a *proposal* (awaiting
+confirmation) to tag "regenerate code-specs `[auto]`".
+
+---
+
+## What this skill does NOT do
+
+- Does not run the Observe stage -- it reads the usage log; it does not write session signals.
+- Does not execute any routine, autonomously or otherwise -- surfacing only.
+- Does not add an `[auto]` tag -- it proposes; the developer confirms.
+- Does not auto-promote a routine to `~/.claude/CLAUDE.md` -- it proposes; the developer decides.
+- Does not write a routine below the minimum-observation threshold.
+- Does not read the Observe log without consent set (Observe is opt-in, off by default).
+- Does not write any record to the usage log without first running the scrub/redaction pass.
+- Does not capture command arguments, file contents, diffs, or prompt/response text.
+- Does not copy machine-local log contents into any versioned or promoted file.
+- Does not silently delete a retired routine -- it archives to `memory/retired/` with a tombstone.
+- Does not re-write a routine retired within the cool-off window -- it surfaces it as a candidate.
+- Does not modify `user`/`project`/`feedback`/`reference` memory entries -- it only adds and
+  maintains `procedural` entries.
+
+---
+
+## Version note
+
+v0.2.0 is aligned with `standards/workflows/procedural-memory.md` at v0.2.0 (`status: draft`,
+ready for consolidation review). It implements the now-decided decay/retirement lifecycle (D1)
+and Observe-stage privacy policy (D2). The distill cadence (weekly placeholder), the
+minimum-observation threshold (`>= 3 sessions`), the cross-repo promotion rule, and the lifecycle
+numbers (initial confidence 0.6, +0.1/-0.2 steps, 0.3 floor, 90-day staleness, 30-day cool-off)
+are all provisional. They will be revisited and firmed up when the standard reaches
+`status: reviewed`; this skill should be re-versioned to match.

data/.ai-assistance/standards-version.json

@@ -1,21 +1,22 @@
-{
-  "ep-ai-standards-version": "1.5.0",
-  "applied-at": "2026-06-13",
-  "project-type": [
-    "ruby"
-  ],
-  "deferred": [],
-  "installed-components": {
-    "skills/code-specs": "0.0.0",
-    "skills/ep-ai-manager": "2.1.0",
-    "skills/dep-graph": "0.0.0",
-    "skills/corporate-policies": "1.0.0",
-    "skills/ai-instructions": "0.0.0",
-    "skills/spec-generation": "0.0.0",
-    "skills/gemini-assist": "0.0.0",
-    "skills/ruby-scripting": "0.1.0",
-    "skills/refactor": "0.0.0",
-    "skills/project-cycle": "0.0.0",
-    "skills/graphql-schema-analysis": "0.0.0"
-  }
+{
+  "ep-ai-standards-version": "1.5.0",
+  "applied-at": "2026-06-13",
+  "project-type": [
+    "ruby"
+  ],
+  "deferred": [],
+  "installed-components": {
+    "skills/code-specs": "0.0.0",
+    "skills/ep-ai-manager": "2.1.0",
+    "skills/dep-graph": "0.0.0",
+    "skills/corporate-policies": "1.0.0",
+    "skills/ai-instructions": "0.0.0",
+    "skills/spec-generation": "0.0.0",
+    "skills/gemini-assist": "0.0.0",
+    "skills/ruby-scripting": "0.1.0",
+    "skills/refactor": "0.0.0",
+    "skills/project-cycle": "0.0.0",
+    "skills/graphql-schema-analysis": "0.0.0",
+    "skills/procedural-memory": "0.2.0"
+  }
 }

data/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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