ecoportal-api-graphql 1.3.10 → 1.3.11

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

@@ -0,0 +1,97 @@
+# TODOs — Template Automatic Build & Maintenance  ★ #1 PRIORITY
+
+Legend: `[ ]` todo · `[~]` in progress · `[x]` done · `[!]` blocked
+Domain reference: `.ai-assistance/code/template_diff_pairing_domain.md`
+Code spec: `.ai-assistance/code/diff_pairing_engine.md`
+
+This merges the former `template-diff-deploy/TODO.md` (MAINTAIN track) and
+`template-maintenance/DESIGN.md`+`PHASE0-FINDINGS.md` (BUILD track). BUILD and DIFF-DEPLOY share ONE
+emission layer: an ordered `WorkflowCommand` batch with `placeholderId` threading.
+
+---
+
+## MAINTAIN track (diff → deploy → verify → monitor)
+
+### Phase 1 — Self-version diff (same object, exact)  ✅ DONE
+- [x] `Diff::VersionDiff` — two same-id snapshots → structured changelog (stages/sections/fields/options).
+- [x] `Diff::Change` — command-ready (op/kind/id/before/after) + human `#description`.
+
+### Phase 2 — Expose genome + Change→commands  ✅ DONE
+- [x] `genomeSignature` on the data-field fragment + `Base::Page::DataField` (`passthrough`).
+- [x] `Diff::CommandSynthesizer` — `[Change]` → ordered built `WorkflowCommand` batch; edit-mode moves
+  gated on `Diff::IdResolver`; type change / resolver-less move → UNSUPPORTED (never guessed).
+- [x] `Diff::Deploy` — `from_versions(before, after, target_doc:)`; `#execute!` gates on `unsupported`.
+
+### Phase 3 — Pairing engine (equivalence)  ✅ DONE
+- [x] `Diff::Pairing::Engine` + `Signals` (genome 0.5 / type 0.2 / label 0.2 / options 0.1), greedy 1:1,
+  auto-accept ≥0.85 unless near-tie, ambiguous 0.5–0.85, unmatched <0.5; genome fallible (0 not veto).
+- [x] `Diff::Pairing::Ledger` — persisted confirmed pairs (consulted first; supersede-on-correct).
+- [x] `Engine#confirm!(candidate, matched_by: :human)` assisted-resolution hook.
+- [ ] TODO (eco-helpers): interactive assisted-resolution UX; `TypedFieldsPairing` as an extra signal;
+  live A/B parity harness.
+
+### Phase 3b — Gauge-stop + typed byType config emission + placeholderId threading  ✅ DONE
+- [x] `VersionDiff` emits `:gauge_stop` + `:field_config` (byType, data-driven `BYTYPE_CONFIG`,
+  conservative — only confirmed read↔byType-key matches; unmappable props NOT fabricated).
+- [x] `CommandSynthesizer` maps them; `thread_placeholders:` id-threading primitive (Deploy → on).
+
+### Phase 4 — Diff modalities (composable strategies)  ✅ DONE 2026-07-04 (branch `feature/template-phase4-modalities-builder-docs`)
+- [x] `Diff::Strategy` value object over the four axes: pairing `:id|:genome|:type_label|:assisted` ×
+  scope `:structural|:config_only|:data_migration` × move-sensitivity × intent
+  `:changelog|:deploy|:sync_readiness`. Validates axes; `#filter(changes)` applies scope +
+  move-sensitivity; `.default` reproduces the pre-Phase-4 self-version behaviour EXACTLY (BC).
+- [x] `VersionDiff.new(before, after, strategy:)` — the `:id` front-end now filters its computed
+  change-set through the strategy (default = unchanged; specs prove BC + config_only + move-insensitive).
+- [x] `Diff::CrossObjectDiff` — the CROSS-OBJECT front-end: pairs FIELDS via `Pairing::Engine` (+ optional
+  `Ledger`), builds the id-correspondence map from the ACCEPTED pairs, then emits the SAME `Change`
+  output (relabel/retype on paired fields; target-only → :added; confidently-unpaired source → :removed).
+  Ambiguous/unmatched (incl. same-genome relabels + near-ties) are held in `#unresolved` for a human —
+  NEVER auto-paired, auto-added, or auto-removed. Feeds `CommandSynthesizer`/`Deploy` unchanged.
+- [x] `Deploy.from_cross_object(source, target, engine:, strategy:)` + `Deploy#pairing` (exposes
+  accepted/ambiguous/unmatched for adjudication before apply).
+- [x] Specs: `strategy_spec` (16), `cross_object_diff_spec`, `version_diff_modalities_spec`. Full diff
+  suite 120 examples (was 93; +27). Rubocop clean.
+
+### Phase 5 — Deploy + verify + monitor  (NEXT)
+- [ ] UAT→PROD replay end-to-end: pair → diff → delta commands → apply → verify via `ecoportal-qa`.
+- [ ] Pre/post self-version diff on PROD to confirm the recreation matches the intended delta.
+- [ ] Sync-readiness monitoring: which registers/subsets can sync to their active template.
+
+---
+
+## BUILD track (build-from-scratch → verify)
+
+### Phase B0 — Study & capture  ✅ DONE (see `template-maintenance/PHASE0-FINDINGS.md`)
+- [x] `Builder::Template#create/update(commands:)` + `Input::WorkflowCommand` are the apply facade.
+- [x] `placeholderId` is the id-threading primitive (client-chosen, resolved intra-batch).
+- [x] `tests/dump_template_model.rb` captures a template's structural page doc; reference target
+  `6a3fa5b8f89e07c758df622b` (needs sandbox creds to run live).
+
+### Phase B1 — Gem-level BUILD emitter (unified with diff)  ✅ DONE 2026-07-04 (branch `feature/template-phase4-modalities-builder-docs`)
+- [x] `Builder::TemplateBuilder` — declarative spec (stages→sections→fields→options→config→gauge-stops)
+  → ordered `WorkflowCommand` batch, `placeholderId`-threaded. Order: addStage → addSection →
+  addStageSection → editSectionHeader → addField → addSelectFieldOption / addGaugeFieldStop /
+  editFieldConfiguration(byType:). Verified against `Builder::Template#create/update(commands:)` + the
+  real input classes' VALID_KEYS (only valid keys emitted; nothing fabricated — config passed through
+  under its byType sub-hash exactly as supplied). Shares the SAME `placeholderId` threading concept as
+  `Diff::CommandSynthesizer`. 13 specs. Rubocop clean.
+- [ ] UNSUPPORTED/deferred here (honest): forces/strategies/callbacks/tasks/recipients in a build spec
+  (the command inputs exist but the build spec shape for them was not confirmed — add per confirmed
+  shape); `field_type` enum values not validated against the schema (passed through as given).
+
+### Phase B2 — Live characterization  (NEXT, needs sandbox)
+- [ ] Replay `TemplateBuilder` output to reconstruct sample `6a3fa5b8…622b`; assert structure-equivalence
+  vs the pinned `dump_template_model.rb` fixture. `executeWorkflowCommands` mutates → sandbox, not CI.
+
+### Phase B3 — CSV→templates pipeline  (later, deadline ~Sept 2026)
+- [ ] CSV extract → `TemplateBuilder` spec → build batch, for the 300+ template delivery. Section/field
+  identity via hidden-field + description (see memory: project-template-csv-pipeline).
+
+---
+
+## Cross-cutting
+- [ ] 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).
+- [ ] Extend `BYTYPE_CONFIG` per field type as read↔byType-key shapes are confirmed; gauge-stop reorder.
+- [ ] Complete the `PagesWorkflow.stages` read model to unblock workflow-config-per-stage diff.

data/.ai-assistance/projects/template-diff-deploy/INTENT.md

@@ -0,0 +1,12 @@
+# MOVED → `template-automatic-build-maintenance`  ★ #1 PRIORITY
+
+This project has been **merged** into the unified **Template Automatic Build & Maintenance** project.
+
+- Single INTENT: `../template-automatic-build-maintenance/INTENT.md`
+- Single TODO:   `../template-automatic-build-maintenance/TODO.md`
+
+The MAINTAIN track (diff → deploy → verify → monitor) that lived here is now the "MAINTAIN track"
+section of the merged TODO. Nothing here is authoritative any more — do not update this folder.
+
+Domain reference (unchanged): `.ai-assistance/code/template_diff_pairing_domain.md`.
+Code spec (unchanged): `.ai-assistance/code/diff_pairing_engine.md`.

data/.ai-assistance/projects/template-diff-deploy/TODO.md

@@ -0,0 +1,9 @@
+# MOVED → `template-automatic-build-maintenance/TODO.md`
+
+The diff/deploy TODOs (Phases 1–5) are now the **MAINTAIN track** of the merged
+**Template Automatic Build & Maintenance** project (★ #1 priority):
+
+→ `../template-automatic-build-maintenance/TODO.md`
+
+Phases 1–3b + Phase 4 (diff modalities: `Diff::Strategy` + `CrossObjectDiff`) are DONE there.
+Do not add TODOs here.

data/.ai-assistance/projects/template-maintenance/PHASE0-FINDINGS.md

@@ -0,0 +1,93 @@
+# Template-Maintenance — Phase 0 Findings (2026-07-02)
+
+Ground-truth survey of the gem + eco-helpers surface, verified against actual code (not the
+DESIGN.md second-hand survey). Corrections to DESIGN.md assumptions are flagged **⚠**.
+
+---
+
+## 1. The gem mutation surface is MORE complete than DESIGN.md implied
+
+- **⚠ `Builder::Template` already exists and is wired** (`lib/ecoportal/api/graphql/builder/template.rb`,
+  exposed as `GraphQL#template`, `graphql.rb:98`). It offers:
+  `create(commands:)`, `update(model, commands:, patch_ver:)`, `publish(id:)`, `unpublish(id:)`,
+  `update_information(id:, ...)`, `create_related_page(...)`, `destroy_related_page(...)`.
+  → The template create/update **apply** step is done. We do **not** need to build a new facade
+  for `executeWorkflowCommands` on the template side — `Builder::Template#create/update` already
+  wrap `Mutation::Template::{Create,Update}` with a `commands:` array.
+- `Builder::Page#execute_workflow_commands` also exists (per `builder/CLAUDE.md`) for the
+  page-level workflow command path.
+- `Input::WorkflowCommand` (`input/workflow_command.rb`) is the command registry:
+  **108 commands** in `COMMAND_MAP`, `SCHEMA_VERSION = '20260605'`, with:
+  - `.build(command_key, **kwargs)` → `{ key => sliced_kwargs }` (validates key, slices to VALID_KEYS, compacts nils, keeps false)
+  - `.build_commands(specs)` → maps an ordered array of single-key specs into the batch
+  - `.valid_key?(key)`
+
+## 2. A template IS a page (read path)
+
+- **⚠ DESIGN.md Open Question #2 ("is PagesWorkflow read complete enough to diff a template?")
+  is partly moot for STRUCTURE.** `Query::Templates` returns `PageUnion` nodes with `PageFields`
+  — a template is read as an ordinary page. So the structural skeleton
+  (**stages → sections → components(fields)**) comes from the page model, exactly like a live page.
+  `dump_template_model.rb` therefore reuses `api.pages.get(id)` for structure.
+- The `PagesWorkflow` read model (`base/pages_workflow.rb`) is the **workflow-command config**
+  layer (callbacks, operations, triggers, strategies, recipients). **⚠ It is partial:** `stages`
+  is a bare `passarray` (no per-stage strategy/section tree). So:
+  - **Build-from-scratch (Phase 2): UNBLOCKED.** Emit commands, execute, read the page back to verify.
+  - **Structural diff (Phase 4): mostly UNBLOCKED** via the page model (stages/sections/fields).
+  - **Workflow-config diff (callbacks/strategies per stage): BLOCKED** on completing the
+    `PagesWorkflow.stages` read model. Track as a Phase-4 dependency, not a Phase-2 blocker.
+- Forces read is on the page model but `Query::PageWithForces` is WIP (see forces notes) — a
+  forces-aware diff is a later dependency.
+
+## 3. `placeholderId` is the id-threading primitive (the key design fact)
+
+The location-structure engine threads server-assigned ids **post-hoc** (zip input↔result, extract
+`newId`, remap table). **The workflow command bus does NOT need that** — it uses **client-chosen
+`placeholderId`s resolved intra-batch**:
+
+| Command | Placeholder it defines | References (by placeholder or real id) |
+|---|---|---|
+| `addStage` | `placeholderId` | — |
+| `addSection` | `placeholderId` | — |
+| `addStageSection` | — | `stageId`, `sectionId` |
+| `addField` | `placeholderId` | `stageId`, `sectionId`, `column` |
+| `addSelectFieldOption` | `placeholderId` | `dataFieldId` |
+| `addForce` | `placeholderId` | — |
+| `addBinding` | `placeholderId` | `forceId` |
+
+→ The emitter assigns a stable `placeholderId` to every new node and references it downstream in
+the **same batch**. This is simpler than the location `track_changed_ids` remap. **⚠ Correction to
+DESIGN.md:** we mirror the location engine's *shape* (DSL → ordered commands → apply → read-back),
+but the id-threading is placeholder-based, not `newId`-remap-based.
+
+**Open question to confirm live:** does `executeWorkflowCommands` resolve placeholderIds across the
+*whole* batch, or only within ordering constraints (e.g. must addStage precede addStageSection)?
+The emitter already emits in dependency order (stage → section → stageSection → field → option),
+so this is safe either way; confirm during the Phase-3 sandbox replay.
+
+## 4. What Phase 0 delivered (this commit)
+
+- `tests/dump_template_model.rb` — captures a template's structural page doc
+  (`spec/fixtures/templates/<id>.json`) + best-effort workflow command log
+  (`<id>.commands.json`). Mirrors `dump_page_model.rb`; run `--label before/after` around a batch
+  to diff. **Reference target:** sample `6a3fa5b8f89e07c758df622b` (needs a live/sandbox org to run).
+- `spec/.../input/workflow_command_serialization_spec.rb` — offline serialization contract for the
+  structural command families + the `build_commands` ordered-emitter shape + placeholderId threading.
+  10 examples, green. This is the net the eco-helpers emitter is written against.
+
+## 5. Revised phase view
+
+- **Phase 1 (gem):** DONE-ENOUGH. `Builder::Template` + `Input::WorkflowCommand` are the facade;
+  offline command specs exist and grow as new command types are exercised.
+- **Phase 2 (eco-helpers):** `samples/pages/template/{base,dsl}.rb` + a command-emitter service
+  (DSL → ordered commands w/ placeholderId threading → `Builder::Template#create/update` → read-back).
+  Offline emitter specs are fully achievable without live calls.
+- **Phase 3 (sandbox):** replay to reconstruct `6a3fa5b8…622b`; assert structure-equivalence vs the
+  `dump_template_model.rb` fixture. Needs a sandbox org (Open Question #1 — creds TBD).
+- **Phase 4 (diff):** structural diff via page model now; workflow-config diff waits on the
+  `PagesWorkflow.stages` read model.
+
+## Open questions still owned by Oscar
+1. Sandbox org + creds for the Phase-3 live characterization harness.
+2. Priority of completing the `PagesWorkflow.stages` read model (gates workflow-config diff).
+3. Does `6a3fa5b8…622b` exercise forces? (gates the forces read/write split for its replay)

data/.ai-assistance/projects/template-maintenance/README.md

@@ -0,0 +1,14 @@
+# MOVED → `template-automatic-build-maintenance`  ★ #1 PRIORITY
+
+This project has been **merged** into the unified **Template Automatic Build & Maintenance** project.
+
+- Single INTENT: `../template-automatic-build-maintenance/INTENT.md`
+- Single TODO:   `../template-automatic-build-maintenance/TODO.md`
+
+The BUILD track (build-from-scratch → verify → CSV pipeline) that lived here is now the "BUILD track"
+section of the merged TODO. The gem-level BUILD emitter is DONE
+(`Builder::TemplateBuilder`, shares the diff's `placeholderId` emission layer).
+
+`DESIGN.md` and `PHASE0-FINDINGS.md` are RETAINED here as background — the merged INTENT/TODO reference
+them for the survey + the `placeholderId` id-threading facts. They are historical context, not the
+active task list. Do not add new TODOs here — use the merged TODO.

data/CHANGELOG.md

@@ -2,6 +2,93 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.3.11] - 2026-07-04
+
+Template automatic **build & maintenance** engine (backwards-compatible — a self-contained new
+`Diff` module + a build emitter; nothing existing changed). Validated **offline** (specs + fixtures +
+shapes checked against the live schema dump); the live UAT→PROD round trip is pending a sandbox org.
+
+### Added
+
+- **`genomeSignature`** fetched on every data-field type (added once to the `dataFieldInterface`
+  fragment, `@skip(if: $only_content)`) + `passthrough :genomeSignature` on `Base::Page::DataField` —
+  a strong-but-fallible field-pairing signal.
+- **`Diff::VersionDiff`** — two same-object (retained-id) template snapshots → an exact structural
+  changelog: added/removed/changed/moved for stages, sections, fields (label/type/section-move),
+  select options (label/weight), **gauge stops** (add/remove/threshold/color, matched by stop id), and
+  typed **`byType` field config** (conservative, only confirmed read↔input-key matches: Gauge `max`;
+  Select `dataType/multiple/flat/other/otherDesc`; Date `showTime/pastOnly/todayButton`).
+- **`Diff::Change`** — command-ready change (`op`/`kind`/`id`/`label`/`path`/`attribute`/`before`/
+  `after`/`parent_id`/`by_type`) with a human `#description`; `#to_h` is the stable interchange shape.
+- **`Diff::CommandSynthesizer`** — a `Change` set → an ordered `WorkflowCommand` batch (the replayable
+  "commit"): moves/renames/config, options, gauge stops, `editFieldConfiguration(byType:)`, with
+  **`placeholderId` threading** so dependent intra-batch creates reference not-yet-created nodes.
+  Genuinely ambiguous cases (field type change, moves without a target id) are left **UNSUPPORTED** —
+  never guessed.
+- **`Diff::Deploy`** — `from_versions(before, after, target_doc:)` / `from_cross_object(...)` produce
+  the ordered batch ready for `executeWorkflowCommands`; `#execute!` refuses to run while the honest
+  `unsupported` list is non-empty unless `allow_partial: true`; inert until an executor is passed.
+- **`Diff::IdResolver`** — indexes a target doc's stage names + section headings → ids for move
+  resolution; duplicate keys resolve to `nil` (never guesses).
+- **`Diff::Pairing::{Engine,Signals,Candidate,Ledger}`** — multi-signal equivalence matching for
+  cross-object templates (genome 0.5 + type 0.2 + label 0.2 + options-by-value 0.1, averaged over
+  applicable signals; greedy 1:1; auto-accept ≥0.85, ambiguous 0.5–0.85, unmatched <0.5; genome
+  mismatch scores 0 but does **not** veto). `Ledger` persists confirmed pairs (consulted first;
+  human corrections supersede).
+- **`Diff::Strategy`** — composable diff modalities: pairing (`:id`/`:genome`/`:type_label`/
+  `:assisted`) × scope (`:structural`/`:config_only`/`:data_migration`) × move-sensitivity × intent
+  (`:changelog`/`:deploy`/`:sync_readiness`). `.default` reproduces exact pre-existing behaviour.
+- **`Diff::CrossObjectDiff`** — diffs two templates with **no shared ids** by building the
+  id-correspondence map via `Pairing::Engine` (+ optional `Ledger`), then emitting the same `Change`
+  output that feeds `CommandSynthesizer`/`Deploy`. Ambiguous/unmatched held in `#unresolved` for a
+  human — never auto-paired.
+- **`Builder::TemplateBuilder`** — a declarative template spec (stages→sections→fields→options→
+  config→gauge-stops) → an ordered `WorkflowCommand` batch for `Builder::Template#create/update`,
+  using the **same `placeholderId` threading** as the diff synthesizer so build-from-scratch and
+  diff-deploy emit through one layer. Emits only verified input `VALID_KEYS`. A field's `description`
+  (e.g. a CSV/hidden-field identity token) is emitted as a follow-up `editFieldConfiguration(
+  dataFieldId:, description:)` — the correct schema seam, since `WorkflowAddFieldInput` has no
+  `description` key.
+- **Stage/section back-refs on added nodes** (`Diff::CommandSynthesizer`) — an added field's `addField`
+  now carries `sectionId` (`Change#parent_id`) + `stageId` (new `Change#owner_id`); an added section
+  emits a follow-up `addStageSection(stageId:, sectionId:)`. All threaded via `ref()` (parent
+  placeholder when created same-batch, else real id; omitted when unknown → historical behaviour
+  unchanged). `VersionDiff` records `parent_id`/`owner_id` on added field/section changes.
+
+### Fixed
+
+- **Fragment references migrated to the `spread :Name` registry convention.** The Action and
+  ContractorEntity **mutations** (`create`/`update`/`destroy`, `create`/`update`/`archive`) still used
+  the dead `___Const__Fragment` convention, which resolves a Ruby constant `Fragment::<Name>` that no
+  longer exists (fragments are a registry now) → `uninitialized constant … Fragment::… (NameError)` at
+  render time. Now `spread :Action` / `spread :ContractorEntity`, matching the already-migrated queries.
+  (The sibling breakage in eco-helpers' location-command optimizations is fixed in eco-helpers 3.2.17;
+  it crashed the live act-gov locations sync.)
+- **Kickstand workflow mutations — bare `DateTime` selection.** `Kickstand::{Start,Stop,Fail}Workflow`
+  selected `startedAt`/`stoppedAt`/`failedAt` bare → "Field must have selections". Now
+  `{ dateTime timeZone }` (same class as the 1.3.10 LocationStructure fix).
+- **`tests/validate_queries.rb` now renders MUTATIONS too** (was queries only) and **hard-fails on a
+  render error** (dead fragment / unresolved constant), not just a soft skip — the offline guard for
+  both classes above. It caught the 3 Kickstand bugs immediately.
+
+### Schema realities (verified against the live introspection dump)
+
+- **`required` cannot be set via the workflow command bus** — there is NO `required` input key anywhere
+  in the schema (not on `WorkflowAddFieldInput`, not on `WorkflowEditFieldConfigurationInput` or any of
+  its 12 byType sub-inputs). Callers must treat field-`required` as **read-only / out-of-band**
+  (ecoportal-qa `:skip`s `required`-readiness by design).
+
+### Dependencies
+
+- **Requires `ecoportal-api-v2 >= 3.3.3`** (was `>= 3.3.2`). 3.3.2 has a Ruby-3.x `TypeError` in the
+  `DoubleModel` cascade (`_cascaded_attributes_trace`) that crashes `as_update`/`DiffService` on any
+  model with nested attributes — fixed in v2 3.3.3. Raising the floor stops the broken v2 from
+  resolving on consumers.
+
+### Known gaps (tracked, not in this release)
+
+- Live characterization (UAT→PROD replay + verify) is pending a sandbox org + credentials.
+
 ## [1.3.10] - 2026-07-03
 
 Hotfix (backwards-compatible). Resolves a live failure on the Turners & Growers users sync.

data/docs/worklog.md

@@ -8,6 +8,285 @@ This file tracks cross-project session state and the overall repo status.
 
 ---
 
+## ▶ SESSION 2026-07-06 — RELEASED the fixed stack; act-gov tagtree + toocs live-green
+
+The 2026-07-05 crash-fixing arc shipped. **All three live-verified green** on act-gov (direct
+`-no-email` runs): **tagtree-update** (created draft → 8 insert / 3 archive → published, no customer
+email) and **toocs-coding** (Oscar confirmed). Released, in dependency order:
+- **ecoportal-api-v2 `v3.3.3`** — Ruby-3.x cascade block-param fix + regression spec.
+- **ecoportal-api-graphql `v1.3.11`** — Diff build+maintenance engine; fragment-convention + Kickstand
+  DateTime fixes; requires v2 >= 3.3.3; validate_queries now covers mutations + hard-fails on render.
+- **eco-helpers `v3.2.17`** — native template build+maintenance + ooze-native; location fragment
+  (`spread :LocationDraft`) + `worfklow` no-email typo fixes; requires gem >= 1.3.11 + v2 >= 3.3.3.
+- **multi_org_api** (`master` + `api-deprecation`) — `-no-email` now forwarded through the rake
+  wrapper + `worfklow` typo fixed (stops customer emails during rake/scheduled tests).
+
+Oscar git-pushed all repos + gem-published; **deploying via server `bundle update ecoportal-api-v2
+ecoportal-api-graphql eco-helpers`** (production Gemfile floors gem>=1.3.9/eco-helpers>=3.2.16, but the
+gemspec floors force v2>=3.3.3 + gem>=1.3.11 transitively). Systemic guard against the recurring
+stale-release drift: raised gemspec dependency FLOORS everywhere + extended `validate_queries.rb`.
+
+**STILL OPEN (non-blocking):** rake `notify_exception` emails the customer on task error regardless of
+`-no-email` — decision pending (suppress / route-to-dev / keep). See [[no-email-leak-paths]].
+
+---
+
+## ▶ 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
 

data/lib/ecoportal/api/graphql/base/page/data_field.rb

@@ -54,7 +54,7 @@ module Ecoportal
             }.freeze
 
             passkey :id
-            passthrough :label, :deindex
+            passthrough :label, :deindex, :genomeSignature
             # __typename is stored under the 'type' key after mapping
             passthrough :type