ecoportal-api-graphql 1.3.10 → 1.3.12

data/docs/self-docs/CONVENTIONS.md

@@ -0,0 +1,74 @@
+---
+schema_version: "1.0"
+repo: "ecoportal-api-graphql"
+doc: conventions
+last_generated: "2026-07-06"
+source_head: "2abd6fc"
+review_status: draft
+---
+
+# Conventions -- ecoportal-api-graphql
+
+**Source of truth:** `.rubocop.yml` (repo root) and `CLAUDE.md`. There is no `ai-discovery`
+`conventions.md` in this repo; the below is composed from `.rubocop.yml`, `CLAUDE.md`, and observed
+git history, not re-derived from code.
+
+## Code style
+
+- Indentation: 2 spaces (Ruby default; no override in `.rubocop.yml`).
+- Quotes: not enforced -- `Style/StringLiterals` is disabled, so single and double quotes are both
+  accepted.
+- Line length: unlimited -- `Layout/LineLength` is disabled.
+- Frozen string literal comment: not required (`Style/FrozenStringLiteralComment` disabled).
+- Hash alignment: table style for both colon and hash-rocket (`Layout/HashAlignment`).
+- Dot position: trailing (`Layout/DotPosition`).
+- Alias: prefer `alias_method` (`Style/Alias`).
+- Notable relaxed metrics: `ClassLength` 350, `ModuleLength` 400, `MethodLength` 100,
+  `AbcSize` 30, `CyclomaticComplexity`/`PerceivedComplexity` 30, `ParameterLists` 5.
+- Naming exceptions: camelCase method/variable names are allowed where they mirror GraphQL/Relay
+  schema fields verbatim (`Naming/MethodName` disabled; `clientMutationId` allow-listed). This is
+  intentional -- the client mirrors the schema.
+- Rubocop compliance is required for all generated Ruby: run `bundle exec rubocop <file>` to verify.
+
+## Branch naming
+
+Type-prefixed, slash-separated. Observed prefixes in the branch list and history:
+`feat/<slug>`, `fix/<slug>`, `docs/<slug>`, `chore/<slug>`, and longer-lived `feature/<slug>`
+branches for multi-phase work. Note: `pages` is a long-running primary development branch that
+predates the prefix convention.
+
+## Commit message style
+
+Conventional Commits: `type(scope): message`. Observed types include `feat`, `fix`, `docs`,
+`chore`, and `merge`. Scopes are area-based, e.g. `feat(diff/builder):`, `docs(worklog):`,
+`chore(release):`, `docs(template-automation):`. Release commits follow
+`chore(release): vX.Y.Z ...`.
+
+## Test conventions
+
+- Runner: RSpec (`bundle exec rspec`).
+- Placement: spec files mirror the `lib/` structure under `spec/` (e.g.
+  `spec/ecoportal/api/graphql/input/search_conf_spec.rb`).
+- Live tests: tagged `--tag live`; `.env` is loaded via `dotenv` in `spec_helper.rb`
+  (needs `ANTHROPIC_API_KEY` for live AI tests).
+- Manual integration scripts live under `tests/` (separate from the RSpec suite).
+- Coverage is known to be sparse in subdirectories (see `.ai-assistance/code/spec_coverage.md`).
+
+## Project-specific rules
+
+From `CLAUDE.md`:
+
+- Namespace: `Ecoportal::API::GraphQL` (capital G, Q, L); file paths use lowercase `graphql/`.
+- File/class mirroring: file path mirrors the class namespace exactly.
+- Code-spec docs: for every area analysed, a corresponding `.ai-assistance/code/<area>.md` should
+  exist or be created/updated.
+- No silent breaking changes: any change to the gem's public interface must be noted in the active
+  project's DECISIONS log and confirmed with the developer. Backwards compatibility with
+  `eco-helpers` must be preserved unless explicitly broken.
+- Gemini responses must be verified against actual code before applying.
+- Commit authorship: developer only by default; do not add `Co-Authored-By: Claude ...` unless the
+  developer explicitly requests it.
+- Verified Platform Knowledge: consult `.ai-assistance/code/ecoPortal_architecture/` before
+  implementing platform logic; record newly confirmed platform facts there with evidence (ADR-012).
+- Working-tree safety: follow `.ai-assistance/conventions/code-working-tree-protocol.md` (bridge
+  LOCK, commit overlapping unstaged changes as `wip:` first) before modifying files.

data/docs/self-docs/INTEGRATIONS.md

@@ -0,0 +1,63 @@
+---
+schema_version: "1.0"
+repo: "ecoportal-api-graphql"
+doc: integrations
+last_generated: "2026-07-06"
+source_head: "2abd6fc"
+review_status: draft
+---
+
+# Integrations -- ecoportal-api-graphql
+
+**Purpose:** the ties this project has to other systems and repos. This is the section the central
+hub uses to trace inter-project dependencies and surface reuse (ADR-015 Section 5).
+
+## External services
+
+| Service | Purpose | Notes |
+|---|---|---|
+| ecoPortal GraphQL API | The API this gem is a client for -- reads/writes pages, templates, location structures, contractor entities, actions, organizations. | Auth via `Common::GraphQL::AuthService` (OAuth), scoped by `org_id`; hosted per environment (e.g. live.ecoportal.com). `no_schema: true` -- no introspection. |
+| ecoPortal REST API (v2) | Underlying REST infrastructure the GraphQL layer builds on and stays compatible with via the `Compat` layer. | Provided by the upstream `ecoportal-api-v2` gem. |
+
+## Upstream dependencies (repos we depend on)
+
+| Repo / package | What we use it for |
+|---|---|
+| `ecoportal-api` | REST API base: auth, org context, base models, and the `Ecoportal::API::Common` namespace this gem extends. Team-managed. |
+| `ecoportal-api-v2` | REST API v2 layer (Page, Register, etc.); required by the entry point. Team-managed. Being retired over time. |
+| `graphlient` | Friendly GraphQL DSL/client wrapper; `Common::GraphQL::Client` inherits from `Graphlient::Client`. Active fork owned by the team (upstream: `ashkan18/graphlient`). |
+| `graphql-client` | Low-level GraphQL HTTP + parsing, pulled in transitively via graphlient. Fork for upstream contribution only (upstream: `github-community-projects/graphql-client`); not team-maintained. |
+| `graphql` (graphql-ruby) | Schema definition/execution engine (`rmosolgo/graphql-ruby`); external, read-only reference. Used server-side by ecoPortal; client-side usage here is indirect. |
+
+## Downstream consumers (who depends on us)
+
+- `eco-helpers` -- the primary consumer; an integration-script framework for the ecoPortal
+  Integrations Team. It requires this gem (`ecoportal-api-graphql ~> 1.3, >= 1.3.4`) and relies on
+  the `Compat` layer to treat `graphql` as a drop-in for the older `apiv2` interface. Backwards
+  compatibility with `eco-helpers` must be preserved unless explicitly broken.
+- `ecoportal-qa` -- consumes the gem to verify template deploys (the "verify" step of the template
+  build-and-maintenance pipeline; a `DryRunClient` and `Publisher` were built there). The
+  template-automation project aims to tighten `ecoportal-qa` to consume the gem's page-model.
+
+## Key package dependencies
+
+From `ecoportal-api-graphql.gemspec` (runtime):
+
+- `ecoportal-api` `~> 0.10, >= 0.10.16`
+- `ecoportal-api-v2` `~> 3.3, >= 3.3.3`
+- `graphlient` `>= 0.8.0, < 0.9`
+
+Development: `rspec`, `rubocop` (+ `rubocop-rake`), `rake`, `pry`, `yard`, `redcarpet`.
+Required Ruby: `>= 3.2.2`.
+
+## Feature-request-not-rebuild note
+
+- The template build-and-maintenance capability is developed here in the gem (mechanics: read
+  model, command vocabulary, BUILD emitter, diff, apply, pairing engine + ledger). Orchestration
+  (interactive assisted-resolution UX, session flows) belongs in `eco-helpers`, and verification in
+  `ecoportal-qa`. Before building template/diff/deploy mechanics elsewhere, raise a feature request
+  against this gem rather than duplicating the emission layer.
+- The active template automation is a concrete consumer of the ep-ai-standards
+  `security/ai-service-account-scope` standard: it must authenticate as a dedicated per-org SERVICE
+  ACCOUNT scoped to templates/org-config only, with page records (customer data + PII) structurally
+  out of scope by credential grant. See `.ai-assistance/projects/template-automatic-build-maintenance/INTENT.md`.

data/docs/self-docs/OVERVIEW.md

@@ -0,0 +1,51 @@
+---
+schema_version: "1.0"
+repo: "ecoportal-api-graphql"
+doc: overview
+last_generated: "2026-07-06"
+source_head: "2abd6fc"
+review_status: draft   # draft | reviewed  (only a human sets 'reviewed')
+---
+
+# Overview -- ecoportal-api-graphql
+
+## What this project is
+
+`ecoportal-api-graphql` is a Ruby gem that provides a GraphQL client layer for the ecoPortal
+GraphQL API. It wraps `graphlient` (which itself wraps `graphql-client`) and builds a structured
+layer of models, queries, mutations, fragments, inputs, payloads, and builders on top of it. It
+sits between the upstream ecoPortal REST API gems and downstream consumer code, exposing a
+developer-facing facade for reading and writing ecoPortal domain objects (pages, templates,
+location structures, contractor entities, actions, and organizations).
+
+## Who it serves
+
+Team members -- specifically the ecoPortal Integrations Team and internal script authors. The gem
+is a developer-facing library, not a customer-facing product; its primary consumer is the
+`eco-helpers` integration-script framework. Because it can read and write live customer data
+(page records) through the API, AI caution levels are elevated: the active template-automation
+work is deliberately scoped to a service account covering templates/org-config only, keeping page
+records (customer data + PII) structurally out of scope.
+
+## Current priority
+
+Template Automatic Build and Maintenance (the #1-priority project). This merges the former
+`template-diff-deploy` and `template-maintenance` efforts into one lifecycle: build/maintain 300+
+templates programmatically (a CSV-to-templates pipeline, deadline approximately September 2026)
+and make UAT-to-PROD change replication smooth via a diff/pairing/deploy/verify pipeline. Both
+halves share one emission layer (an ordered `WorkflowCommand` batch with `placeholderId`
+threading).
+
+## At a glance
+
+- Repo type: ruby-gem
+- Primary language / runtime: Ruby (>= 3.2.2)
+- Entry points: `require 'ecoportal/api-graphql'` -> `lib/ecoportal/api-graphql.rb` ->
+  `Ecoportal::API::GraphQL` (`lib/ecoportal/api/graphql.rb`)
+
+## Related self-docs
+
+- Architecture: `ARCHITECTURE.md`
+- Conventions: `CONVENTIONS.md`
+- Integrations: `INTEGRATIONS.md`
+- Status: `STATUS.md`

data/docs/self-docs/STATUS.md

@@ -0,0 +1,69 @@
+---
+schema_version: "1.0"
+repo: "ecoportal-api-graphql"
+doc: status
+last_generated: "2026-07-06"
+source_head: "2abd6fc"
+review_status: draft
+---
+
+# Status -- ecoportal-api-graphql
+
+**Note:** this is the most time-sensitive self-doc. Refresh it at cycle-end and after structural
+changes. Staleness is detectable via `source_head` vs the current git head.
+
+## Active work
+
+Hot paths from the scanner (`lib`, `.ai-assistance`, `spec`, `docs`) plus the active project
+intent. The #1-priority project is Template Automatic Build and Maintenance (see
+`.ai-assistance/projects/template-automatic-build-maintenance/INTENT.md`), which merges the former
+`template-diff-deploy` and `template-maintenance` projects into one lifecycle sharing a single
+`WorkflowCommand` emission layer:
+
+- BUILD: build/maintain 300+ templates programmatically (CSV-to-templates pipeline, deadline
+  approximately September 2026) via a declarative spec -> `Builder::TemplateBuilder` -> ordered
+  command batch -> apply -> verify. Emitter is ready; live characterization is pending sandbox
+  service-account credentials.
+- MAINTAIN / DIFF-DEPLOY: UAT-to-PROD change replication -- detect (diff) -> review -> deploy
+  (delta commands) -> verify -> monitor. Self-version diff, the pairing engine + ledger, diff
+  modalities/`Diff::Strategy`, the cross-object diff path, and `Change`-to-`WorkflowCommand`
+  synthesis are done; the interactive assisted-pairing UX (in `eco-helpers`) is pending.
+- Recent fragment-convention work: Action/ContractorEntity mutations migrated to the spread
+  convention; the query validator now covers mutations.
+
+## Migration state (if any)
+
+- ooze/pages GraphQL-native migration and the api-v2-to-graphql migration are ongoing themes (see
+  `.ai-assistance/projects/ooze-graphql-native-migration/` and `.../api-v2-to-graphql-migration/`).
+  `ecoportal-api-v2` is being retired over time; the `Compat` layer preserves the v2 interface for
+  `eco-helpers` during the transition.
+- Recent releases addressed stale-release drift: v1.3.11 raised the `ecoportal-api-v2` floor to
+  `>= 3.3.3` to fix a Ruby-3.x cascade after three live crashes were traced to version drift.
+
+## Known risks
+
+- Live customer data exposure: the gem can read/write page records (PII). The template automation
+  is the mitigation lever -- it MUST run under a service account scoped to templates/org-config
+  only, enforced by credential grant, not by instruction (ep-ai-standards
+  `security/ai-service-account-scope`). Provisioning that concrete grant is now this repo's work,
+  not a platform blocker.
+- Backwards compatibility with `eco-helpers` is a hard constraint; public-interface changes must be
+  logged in the active project's DECISIONS log and confirmed with the developer.
+- `no_schema: true` means queries are not validated against a schema at build time -- a query
+  validator (now covering mutations) is the compensating control.
+- Spec coverage is sparse in subdirectories (`.ai-assistance/code/spec_coverage.md`).
+
+## Open questions
+
+- No CI config was detected at the repo root; whether CI runs elsewhere or is absent needs human
+  confirmation.
+- The cross-object equivalence-matching (pairing) problem has no stable identity across independent
+  Mongo objects; it depends partly on Product's forthcoming template-entity-id, which this gem
+  bridges and feeds but does not own.
+- Workflow-config-per-stage diff is out of scope until the `PagesWorkflow.stages` read model is
+  completed.
+
+## Recent changes
+
+First generation of the self-docs set (draft, for the EP Projects Register pilot). Generated at
+git head `2abd6fc` on branch `main`. The machine-readable delta is in `CHANGES.jsonl`.

data/docs/self-docs/self-docs-index.json

@@ -0,0 +1,39 @@
+{
+  "schema_version": "1.0",
+  "generated_at": "2026-07-06T11:15:00Z",
+  "repo_name": "ecoportal-api-graphql",
+  "repo_type": "ruby-gem",
+  "head": "2abd6fc",
+  "docs": [
+    {
+      "file": "docs/self-docs/OVERVIEW.md",
+      "purpose": "What the project is, who it serves, current priority",
+      "exists": true,
+      "content_hash": "391055c9a6a687b9"
+    },
+    {
+      "file": "docs/self-docs/ARCHITECTURE.md",
+      "purpose": "Top-level structure, key components, how they fit",
+      "exists": true,
+      "content_hash": "ad05f25b95b49c00"
+    },
+    {
+      "file": "docs/self-docs/CONVENTIONS.md",
+      "purpose": "Coding style, branch naming, commit style, test conventions",
+      "exists": true,
+      "content_hash": "1649159eb799a7b8"
+    },
+    {
+      "file": "docs/self-docs/INTEGRATIONS.md",
+      "purpose": "External services, upstream/downstream repos, dependencies",
+      "exists": true,
+      "content_hash": "bae9f91748e33af1"
+    },
+    {
+      "file": "docs/self-docs/STATUS.md",
+      "purpose": "Active work, migration state, known risks, open questions",
+      "exists": true,
+      "content_hash": "08841d1d45eea2d6"
+    }
+  ]
+}

data/docs/worklog.md

@@ -8,6 +8,262 @@ This file tracks cross-project session state and the overall repo status.
 
 ---
 
+## ▶ SESSION 2026-07-05 — 3 live act-gov crashes = ONE root cause (stale released gems); fixed-stack floors
+
+Three live crashes on act-gov (`-toocs-coding` + org-structure sync), all the **same class**: the
+server runs **stale RELEASED gems** while the fixes already exist in local/tagged code.
+1. **v2 cascade `TypeError`** (`_cascaded_attributes_trace … is not a symbol nor a string`) via
+   `as_update`/`DiffService` on a `Phased` page — server `ecoportal-api-v2 3.3.2`; fix (Ruby-3.x
+   block-param swap) is commit `6a2b1b5`, released now as **v3.3.3**. See [[v2-cascade-blockparam-332-bug]].
+2. **`updatedAt` "must have selections"** + 3. **`createdAt` "selections can't be made on scalars"** —
+   LocationStructure queries; server gem **1.3.9**; fixed in gem **1.3.10** (already tagged).
+
+**Resolution (release-prepped; publish + server `bundle update` are Oscar's):**
+- v2 **`v3.3.3`** tagged (`03561ed`): CHANGELOG + **cascade regression spec** (double_model_spec, 6 ex green).
+- gem **`1.3.11`** re-tagged (`ad4f788`): gemspec now requires **`ecoportal-api-v2 >= 3.3.3`**.
+- eco-helpers (`ecd5f03f`): gemspec requires **`ecoportal-api-graphql >= 1.3.11` + `ecoportal-api-v2 >= 3.3.3`**.
+- **Systemic guard = raised dependency FLOORS** so `bundle` cannot resolve a broken version again;
+  plus the existing `tests/validate_queries.rb` (query class) + the new cascade regression spec.
+- **LOCAL runs already bind the fixed clones** — `multi_org_api` (branch `api-deprecation`) Gemfile
+  `:local` group path-mounts gem `main` (1.3.11) + v2 `master` (3.3.3).
+
+**Then Oscar ran `-tagtree-update` locally → the version-drift crashes were GONE** (loaded 14126 nodes,
+created the draft), exposing the NEXT layer: **a dead-fragment-convention class.**
+- `uninitialized constant …Fragment::LocationDraft (NameError)` at render — eco-helpers
+  `Helpers::Location::Command::EndPoints::Optimizations` still used the legacy `___Const__Fragment`
+  convention, which evals a `Fragment::<Name>` CONSTANT that no longer exists (fragments are a registry
+  now; `spread :Name`). Fixed → `spread :LocationDraft`/`:LocationsError` (eco-helpers `352a9657`).
+- **Swept the whole class:** the gem's **Action + ContractorEntity MUTATIONS** had the same dead refs
+  (queries were migrated, mutations missed) → `spread :Action`/`:ContractorEntity` (gem `44a4288`).
+- **Systemic guard:** `tests/validate_queries.rb` now renders **mutations** (was queries only) and
+  **hard-fails on render error** (dead fragment / unresolved constant). It immediately caught **3
+  `Kickstand::{Start,Stop,Fail}Workflow` bare-`DateTime`** bugs → fixed `{ dateTime timeZone }`.
+  Validator now **EXIT 0** (fragment + structural buckets clean); suite **635/0/2**, rubocop clean.
+  See [[fragment-spread-convention]]. Remaining validator "OTHER" findings (union/schema-dump-staleness)
+  are pre-existing → separate follow-up with a fresh schema dump.
+- Gem `v1.3.11` re-tagged (`44a4288`); eco-helpers `3.2.17` (`352a9657`); both unpublished.
+  **NEXT: Oscar re-runs `-tagtree-update` + `-toocs-coding` locally to confirm, then publishes + deploys.**
+
+---
+
+## ▶ SESSION 2026-07-04 (cont.) — v1.3.11 tag, addField schema-verified, learnings captured, live-script drafted
+
+Post-round-4 follow-through on the #1 template project. **Gem `v1.3.11` tagged locally** (`fc45db7`,
+unpublished — Oscar pushes/`gem push`); **eco-helpers bumped 3.2.17** (`243822b9`, unpublished).
+- **addField (`5754d7f`, folded into v1.3.11):** schema-verified — `WorkflowAddFieldInput` has NO
+  `description`/`required`; `required` exists NOWHERE in the schema (read-only). `description` now via
+  follow-up `editFieldConfiguration`; added-field/section `stageId`/`sectionId` back-refs emitted. See
+  [[workflow-command-schema-realities]].
+- **Learnings recorded (answering Oscar's "are these learnings?"):** cross-session memory
+  ([[workflow-command-schema-realities]], [[register-membership-via-tags]]) + AI-readable code-spec
+  (`workflow-command-guide.md` "Schema realities" section, `2098415`) + CHANGELOG + this worklog. Prime
+  material for the [[project-graphql-agent-aws]] corpus (GAP_ANALYSIS flagged this exact gap class).
+- **qa tag-superset SyncReadiness (merged, qa `c058782`):** `base_tags ⊆ compiled_tags` register-
+  membership check. **Surfaced a gem read-path gap:** gem has NO `compiledTags`; `baseTags` has an
+  accessor but the `corePageData` fragment fetches only `otherTags`. So live tag-membership `:skip`s
+  until (a) `baseTags` is added to the read fragment (genomeSignature-style one-liner) AND (b) Oscar
+  confirms "compiled tags" semantics (baseTags? base+other? backend-computed incl. inherited/forces?).
+- **Live characterization script drafted (training `feature/template-live-characterization` `ab147f0`,
+  UNMERGED):** `-template-maintenance` case, dry-run default, `-commit` gates the only live write.
+  Offline smoke PASSED against local clones (6 well-formed commands, 0 unsupported, Applier dry-run,
+  DriftReport match?==true). Commands for Oscar in its README. 4 assumptions to confirm (template read
+  path; register-search signature; tag-superset membership; `graphql.page` executor accepts a template
+  workflow batch). Runs only in `ENVIRO_CONTEXT=local` (path-mounted clones) until v1.3.11 is published.
+
+**OPEN for Oscar:** (1) publish gem v1.3.11 + repoint eco-helpers; (2) confirm "compiled tags" semantics
+→ then the `baseTags` fragment fix; (3) set up the Mini test register + before/after template, then run
+the live characterization (dry-run → commit); (4) decide whether the training case sits on `master` or
+`api-deprecation`.
+
+---
+
+## ▶ SESSION 2026-07-04 (cont.) — Template build+maintenance made #1; increments #4 merged; gem v1.3.11 prepped
+
+Oscar set **template automatic build & maintenance as #1 priority**. Ran the usual 3 parallel threads
+(one per repo), all merged to mains, developer-only authorship. Suites **gem 627 (2 pending live-AI) /
+eco-helpers 274 / qa 104 — 0 failures.** Mains: gem `a07f708`→release `70fd252`, eco-helpers `8dc89c45`,
+qa `ac8077c`.
+
+- **Gem (thread A):** `Diff::Strategy` (composable modalities: pairing × scope × move-sensitivity ×
+  intent; `.default` = prior behaviour) + `Diff::CrossObjectDiff` (two templates with NO shared ids →
+  `Pairing::Engine` builds the id map → same `Change` output → `CommandSynthesizer`/`Deploy`;
+  ambiguous held in `#unresolved`) + `Builder::TemplateBuilder` (declarative spec → build command
+  batch, shares the diff's placeholderId threading). Reconciled the two project-doc folders into
+  `.ai-assistance/projects/template-automatic-build-maintenance/` (★#1). +27 diff / +13 builder / +16
+  strategy specs.
+- **eco-helpers (thread B):** native deploy→verify→monitor loop under `samples/pages/template/deploy/`
+  (`Applier` dry-run default / `commit:` + injected executor / refuses on `unsupported` unless
+  `allow_partial:`; `DriftReport` pre/post self-version diff vs intended on an id-free signature;
+  pluggable `Verifier`, `QaVerifier` soft-wires ecoportal-qa only if on load path, else `NullVerifier`;
+  `SyncReadiness` per-entry) + CSV→template build (`FormatMap`→`Parser`→`Builder` →
+  `Builder::Template#create`; format isolated in `FormatMap`). +31 specs.
+- **qa (thread C):** deploy-verification + sync-readiness as new check-sets in the existing framework
+  (two `Runner` entrypoints → canonical `Result`); consumes the gem page-model. Intended-change
+  contract = `{meta, changes:[Change#to_h]}` (accepts wrapper or bare list, sym/str keys); needs a
+  `baseline_doc:` for no-unintended-change; richer gem `Diff::VersionDiff` injectable via
+  `Compiler.new(diff_class:)`. +30 specs.
+
+**★ TWO INDEPENDENTLY-CONFIRMED SEAMS (B and C reached the same conclusions):**
+1. The gem `Diff` module was **unreleased** (1.3.10 was the location hotfix). B/C bind to it via
+   injected/lazy seams so they run offline against released 1.3.9/1.3.10. **→ Prepped gem `v1.3.11`**
+   (`chore(release)` `70fd252`: version bump + full CHANGELOG for the Diff module + `TemplateBuilder`).
+   NOT yet tagged/published — Oscar to tag `v1.3.11` + publish, then repoint eco-helpers to it so the
+   deploy loop binds to the real `Diff` classes.
+2. Gem **`addField` input drops `description`/`required`** → CSV/hidden-field identity token + `required`
+   readiness can't persist through `addField` (C `:skip`s `required`; B keeps only the hidden anchor).
+   Also diff-side `addField`/`addSection` lack `stageId`/`sectionId` back-refs.
+   **✅ RESOLVED (schema-verified, folded into v1.3.11 — merge `d42c528`, retag at `fc45db7`):**
+   introspection shows `WorkflowAddFieldInput` = `{placeholderId,fieldType,label,stageId,sectionId,
+   column}` — **no `description`**, and **`required` exists NOWHERE in the schema** (not on AddField,
+   not on any of the 12 byType edit sub-inputs). So: `description` now persists via a follow-up
+   `editFieldConfiguration(dataFieldId:, description:)` (TemplateBuilder + synthesizer); added-field
+   `addField` carries `sectionId`(parent_id)+`stageId`(new `Change#owner_id`), added-section emits
+   `addStageSection`, all `ref()`-threaded. **`required` is permanently read-only/out-of-band** (qa
+   `:skip` is correct-by-design, not a gap). Suite 635/0/2, rubocop clean.
+
+**STATE OF #1 PROJECT:** full build+maintain engine exists **end-to-end offline** — build (CSV or
+declarative → commands), diff (self-version + cross-object via pairing), deploy (apply + drift-check),
+verify (qa), monitor (sync-readiness). Gap to "trusted" = **(a) publish v1.3.11** (tagged locally at
+`fc45db7`, incl. the addField resolution; push + `gem push` are Oscar's) **+ repoint eco-helpers**
+(bumped to 3.2.17, unpublished), and **(b) the sandbox live pass** (Mini site; a dedicated test
+register + a template whose compiled tags ⊇ the register `base_tags` + a before/after version — see
+[[register-membership-via-tags]]; script to be prepped; sandbox can't reach live.ecoportal.com so
+Oscar runs it). Sync-readiness should also gain the **tag-superset** dimension (register membership =
+`base_tags` ⊆ compiled tags), not just field presence.
+
+---
+
+## ▶ SESSION 2026-07-04 (cont.) — 3 parallel-thread increments #3 merged + strategic briefing captured
+
+**Increments #3 (all merged to mains, green, developer-only authorship):** gem `main` `c607be9`,
+eco-helpers `master` `5adb4a21`, qa `master` `41cb2e6`. Suites **gem 587 (2 pending live-AI) /
+eco-helpers 243 / qa 74 — 0 failures.**
+- **Templates (gem):** `VersionDiff` now **emits** gauge-stop (`add/remove/editGaugeFieldStop`, matched
+  by retained stop id) + typed `byType` field-config changes (`editFieldConfiguration(byType:)`,
+  conservative — only confirmed read-prop↔input-key 1:1: Gauge `max`; Select `dataType/multiple/flat/
+  other/otherDesc`; Date `showTime/pastOnly/todayButton`; shapes verified vs the live schema dump).
+  `CommandSynthesizer` maps them + **placeholderId threading** (Deploy default on): deterministic
+  client placeholders on added nodes, later same-batch refs rewritten via `ref()`. +26 specs.
+  UNSUPPORTED (honest): unconfirmed byType props (PlainText `multiline`/`required`, RichText/People/
+  Table/CrossReference bodies), gauge-stop reorder (no ordering field), structural back-refs in adds.
+- **samples/pages (eco-helpers):** native `TypedFieldsPairing` (groups by GraphQL type string, 2-pass
+  label match, `EXCLUDED_TYPES` TagField/Chart/FrequencyRateChart) + `Copying#copy_field_content` +
+  `Register::MigrationCase < Register::Base`. Ports live FLAT at `graphql/helpers/pages/*` (not the
+  TODO's `.../migration/*`) for round-2 consistency. Deferred: v2 mapped-field hooks
+  (`copy_hooked_fields`/`field_maps`), live A/B parity run (creds). +27 specs.
+- **QA (ecoportal-qa):** sub-phase **3c CLI wiring** (`--jira KEY` → DryRunClient default, offline
+  CI-preview; `--audit-log PATH` JSONL; report-only default) + **3b `RestClient` skeleton**
+  (config-parameterized transition-names/verdict-field, injected HTTP transport, stub-driven specs,
+  no real HTTP). No McpClient. +22 specs. Note: `PHASE3-SCOPE.md`/`ROADMAP.md` live on the gem branch
+  `feature/qa-services-delivery-project` under `.ai-assistance/projects/qa-services-delivery/`, NOT in
+  the qa repo — worklog wording earlier was ambiguous.
+
+**★ STRATEGIC BRIEFING from Oscar (captured to memory — see the index).** The next arc is
+**customer-facing agents/apps**, all governed by a management **no-support-dependency mandate**
+([[principle-customer-facing-automation]]): self-documenting config, auto gap-detection, guide the
+technician, CI/CD that blocks breaking changes + auto-generates self-tested migrations, pricing
+transparency, extensive Confluence docs the AI can pull from. Four threads:
+1. **GraphQL / "Integrations" agent → Claude-on-AWS (Client Services workspace)** — corpus already
+   staged externally (`C:\claude\Projects\Claude AWS Platform\tmp\corpus\staging\success\graphql\`,
+   18 docs), push deliberately held until repo learnings could enrich it. **NOW the moment.** Ships a
+   generic Postman/Insomnia collection + a new Confluence self-serve subsection ("Do it yourself"/
+   Training/Learning/Examples). `.ai-assistance/projects/graphql-agent/GAP_ANALYSIS.md` is the (stale,
+   2026-06-07) gap map — many gaps now filled by code-specs written since. See [[project-graphql-agent-aws]].
+2. **SCIM agent = Entra ID gallery app** — driver: **APIv0 retires END-JUL 2026, FIRM.** Kill the
+   high-touch Entra SCIM enrollment (free Travis). Design gated on a **rich structured Travis
+   interview** + an **Oscar walkthrough of the Entra caveats** (both Oscar-requested, pending). Open:
+   Microsoft Partner vs unlisted-app, gallery upgrade/migration mechanism. See
+   [[project-azure-gallery-app]] + [[project-scim-users-apiv0-adapter]].
+3. **Webhooks** — about to officially release; page payload sends only internal `page_id`. Oscar's
+   private (un-raised) view: should also send `externalId`. See [[project-webhooks-subscriptions]].
+4. **Platform-agnostic integrations (Zapier as referent, not dependency)** — reusable, auto-detects
+   template-drift breakage; UAT-vs-PROD ideal; generic requirements interview with Oscar pending. See
+   [[project-integrations-platform-agnostic]].
+
+**NEXT:** decide with Oscar whether to start the GraphQL-agent corpus enrichment now (in-repo work I
+can do; the actual AWS push needs his creds/workspace). The 3 gem/helpers/qa threads can also continue
+(#4 increments) in parallel as before.
+
+---
+
+## ▶ SESSION 2026-07-04 — 3 parallel-thread increments #2 (all merged to mains, green)
+
+Same shape as the prior session: one background agent per repo, separate working trees, each on a
+feature branch, then **all consolidated to their mains + branches deleted** (Oscar's call),
+developer-only authorship. Suites: **gem 561 (2 pending live-AI, pre-existing) / eco-helpers 216 /
+qa 52 — 0 failures.** Mains: gem `b16b5e5`, eco-helpers `c37847d5`, qa `ec4a507`.
+
+- **Templates (gem) — `template-diff-deploy`:** edit-mode synthesis + deploy orchestration + pairing.
+  `Diff::Deploy.from_versions(before, after, target_doc:)` turns a diff into an ordered replayable
+  `WorkflowCommand` batch for `executeWorkflowCommands`; `execute!` refuses to run while `unsupported`
+  is non-empty unless `allow_partial:`; inert until an explicit executor is passed. Edit-mode moves
+  (`moveField`, section stage-reassign via `removeStageSection`+`addStageSection`) are gated on a new
+  `Diff::IdResolver` (`from_doc` indexes stage names + section headings → ids; duplicate keys → nil,
+  **never guesses**). `Diff::Pairing::{Engine,Ledger,Signals,Candidate}`: weighted fallible signals
+  (genome 0.5 + type 0.2 + label 0.2 + select-options 0.1, averaged over applicable), greedy 1:1,
+  auto-accept ≥0.85 / ambiguous 0.5–0.85 / unmatched <0.5; **genome mismatch scores 0 but does not
+  veto** → contradicting-genome/same-label fields are escalated, never auto-paired. `Ledger` is a
+  first-class JSON artifact of confirmed equivalences, consulted first. Code-spec:
+  `.ai-assistance/code/diff_pairing_engine.md`. +44 diff specs.
+- **samples/pages (eco-helpers):** native `Helpers::Pages::OozeHandlers#merge_values` (dispatches on
+  GraphQL DataField **type string** via `TYPE_MAP`, not V2 Component classes), included into
+  `Register::Base` with `#merge_field_values`. `Compat::Parity::{RunResult,Comparison,Harness}` A/B
+  harness (canonical-KPI + normalised payload snapshot, `equivalent?` verdict) — **pure/offline;
+  running legacy-vs-native live needs a test org + creds.** Native `Register::TargetOozesUpdateCase`
+  (CSV target ids, id-batching, dup-detection preview, fetch-per-id, dedup, KPIs; org-scan `each_page`
+  disabled). Native-only: no case flipped, no shim change, no public-API rename. +38 specs.
+- **QA repo — sub-phase 3a:** `Jira::{Client,DryRunClient,Publisher}`. Jira is *just another Result
+  consumer* (no runner/DSL/compiler/Result changes). DryRunClient writes nothing + records intended
+  posts; Publisher redacts-before-post (ON by default, reuses `Redactor`), per-ticket idempotency
+  marker, **report-only default (never transitions unless a human names one)**, audit trail per
+  action. No RestClient/McpClient (that's blocked 3b/3c). +21 specs.
+
+**NEXT increments (parallel threads continue):**
+- **Templates:** extend `VersionDiff` to *emit* gauge-stop + typed `byType` field-config changes — the
+  one part of edit-mode genuinely blocked upstream in the diff (synthesizer is ready to map them once
+  emitted). Then `placeholderId` threading for dependent intra-batch creates; interactive
+  assisted-resolution UX + `TypedFieldsPairing` as an extra pairing signal (eco-helpers layer).
+- **samples/pages:** live A/B parity run (needs test org + creds); Phase-5 `TypedFieldsPairing` /
+  migration-case porting; later phases flip `OozeSamples::*` to native + shim removal (parity-gated).
+- **QA:** 3b/3c **decision-blocked** on 4 open Qs for Oscar — (1) Jira project + exact transition
+  names, (2) REST service-account token vs MCP-only, (3) verdict field id vs comment-only, (4) where
+  check-sets live long-term. 3a is done and unblocks the offline/CI-preview path today.
+- Standing: 1.3.11 union fixes + CI query-validation TODO (due **2026-07-17**); live capture of
+  template `6a3fa5b8…622b` (blocked on sandbox creds); FARMERS/Travis F1/F2 (`api-deprecation`).
+
+---
+
+## ▶ SESSION 2026-07-03 (cont.) — Consolidation + 3 parallel-thread increments (all merged, green)
+
+**Consolidated** all green foundation branches to their mains (Oscar's call), then built the next
+increment of each of the 3 threads in parallel (one background agent per repo, separate working
+trees). All merged to mains, branches deleted, developer-only authorship. Suites: **gem 515 (~live) /
+eco-helpers 178 / qa 31 — 0 failures.**
+
+- **Templates (gem):** `genomeSignature` now fetched on ALL data-field types (added once to the
+  `dataFieldInterface` fragment, `@skip(if: $only_content)`) + `passthrough :genomeSignature` on
+  `Base::Page::DataField` — unblocks field pairing for cross-template diffs. New
+  `Diff::CommandSynthesizer` turns a `VersionDiff` change-set into an ordered `WorkflowCommand` batch
+  (the replayable "commit"); correctly leaves UNSUPPORTED (never guesses) field type-change and
+  field/section moves (need a pairing map / target id). `Change` gained `parent_id` (stamped on option
+  changes). 
+- **samples/pages (eco-helpers):** native `Samples::Pages::Register::Base < Page::Base` reproducing
+  `RegisterUpdateCase` semantics (register-scoped batched cursor search, dedup-by-id, KPIs, dry-run,
+  process_page/process_ooze override) + native `Helpers::Pages::Creatable`. **Shim + OozeSamples names
+  untouched** (native-only). Deferred (TODO): `merge_values` typed-field pairing; v2 batch_queue dropped
+  (GraphQL is per-page). +17 specs.
+- **QA repo:** dropped the hand-rolled `TemplateModel` (−62 net lines); `Source::{Fixture,Graphql}`
+  now yield the gem's page model (`Model::PageUnion.new(doc)`, parses offline); Compiler navigates gem
+  accessors with small adapters preserving skip-honest options/required/forces. Same toocs verdict (7/2/3).
+
+**NEXT increments (parallel threads continue):** Templates — extend the emitter to *edit* mode +
+wire diff→commands into a deploy flow; pairing engine (uses genomeSignature + type+label) + ledger.
+samples/pages — native `merge_values`/typed-field pairing + A/B parity harness; native
+`TargetOozesUpdateCase`. QA — Phase 3 Jira adapter (decision-blocked). Plus the standing 1.3.11 union
+fixes + CI query-validation TODO (due 2026-07-17).
+
+---
+
 ## ▶ SESSION 2026-07-03 (cont.) — Template self-version diff + genome finding + domain capture
 
 **Built `Ecoportal::API::GraphQL::Diff::VersionDiff`** (gem branch `feature/template-version-diff`,

data/ecoportal-api-graphql.gemspec

@@ -33,7 +33,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'yard',         '>= 0.9.34', '< 1'
 
   spec.add_dependency 'ecoportal-api',    '~> 0.10',  '>= 0.10.16'
-  spec.add_dependency 'ecoportal-api-v2', '~> 3.3',   '>= 3.3.2'
+  spec.add_dependency 'ecoportal-api-v2', '~> 3.3',   '>= 3.3.3'
   spec.add_dependency 'graphlient',       '>= 0.8.0', '< 0.9'
 end