ecoportal-api-graphql 1.3.9 → 1.3.11

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

@@ -0,0 +1,77 @@
+# Project: Template Automatic Build & Maintenance  ★ #1 PRIORITY
+
+**Status:** ACTIVE — the #1-priority project. **Created:** 2026-07-04 (merges the former
+`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`
+**Superseded folders (pointers only now):** `template-diff-deploy/`, `template-maintenance/`.
+**Sibling projects:** `qa-services-delivery` (verify), `ooze-graphql-native-migration`,
+`template-csv-pipeline` (memory).
+
+---
+
+## Why this is one project
+
+Both former projects are two halves of the SAME lifecycle and share ONE emission layer (an ordered
+`WorkflowCommand` batch with `placeholderId` threading applied to `executeWorkflowCommands`):
+
+- **BUILD** (was `template-maintenance`) — build/maintain 300+ templates programmatically
+  (CSV→templates pipeline, deadline ~Sept 2026): declare a desired template → emit an ordered command
+  sequence → apply → read back to verify.
+- **MAINTAIN / DIFF-DEPLOY** (was `template-diff-deploy`) — make UAT→PROD change replication smooth:
+  detect (diff) → review → deploy (delta commands) → verify → monitor, eliminating the two manual
+  regressions (lost PROD-only changes; premature release of unapproved UAT changes).
+
+BUILD is "add everything"; DIFF-DEPLOY is "add/remove/edit only the delta". Same command vocabulary,
+same id-threading, same apply path. Keeping them as one project keeps the emission layer unified.
+
+## The core hard problem (unchanged)
+
+No stable identity across independent Mongo objects (template vs child page, UAT vs PROD). Self-version
+diff (same ids) is trivial and done; cross-object diff is an **equivalence-matching** problem — pair
+fields on multiple weak signals (genome + type + label + options), human-assisted for the ambiguous
+ones, with a persisted **learning ledger**. See the domain reference for the full failure-mode map.
+
+## Approach (confirmed)
+
+- **Self-version diff first** (done) — the portable "commit".
+- **Pairing = equivalence matching**, not identity — multi-signal, confidence-scored, human-in-loop,
+  ledger-backed (`Diff::Pairing::Engine` + `Ledger`; also feeds Product's Field-ID / template-entity-id).
+- **Diff MODALITIES** — a composable family, NOT one diff: `Diff::Strategy` over four axes
+  (pairing `:id|:genome|:type_label|:assisted` × scope `:structural|:config_only|:data_migration` ×
+  move-sensitivity × intent `:changelog|:deploy|:sync_readiness`). `VersionDiff` is the `:id`
+  front-end; `CrossObjectDiff` is the cross-object front-end (pairs fields, emits the SAME `Change`
+  output against the pairing map, consumed by the existing synthesizer/deploy unchanged).
+- **Unified BUILD emitter in the gem** — `Builder::TemplateBuilder` turns a declarative spec into the
+  ordered `WorkflowCommand` batch (stages→sections→fields→options→config→gauge-stops), threading
+  `placeholderId`s exactly as `Diff::CommandSynthesizer` does. BUILD and DIFF-DEPLOY share one layer.
+- **Layering** — mechanics (read model, command vocab, build emitter, diff, apply, pairing engine +
+  ledger) live in the gem so admin/troubleshooting/integration/QA all reuse them; orchestration
+  (interactive assisted-resolution UX, session flows, `TypedFieldsPairing` as an extra signal) is in
+  eco-helpers.
+
+## The pipeline
+
+```
+BUILD:     desired spec ─► TemplateBuilder ─► ordered WorkflowCommands ─► Builder::Template#create/update ─► verify
+MAINTAIN:  pair (id|genome|type_label|assisted+ledger) ─► diff (modality) ─► delta WorkflowCommands
+                 ─► Deploy#execute! (gated on `unsupported`) ─► verify (ecoportal-qa) ─► monitor (sync-ready)
+```
+
+## Scope
+
+- In: self-version diff (done); genomeSignature exposure (done); pairing engine + ledger (done); diff
+  modalities/Strategy (done); cross-object diff path (done); Change→WorkflowCommands synthesis (done);
+  gem-level BUILD emitter (done); UAT→PROD replay; sync-readiness monitoring; CSV→templates pipeline
+  (later); tighten `ecoportal-qa` to consume the gem's page-model.
+- Out: waiting on Product's template-entity-id (we bridge + feed it); auto-applying without human
+  review of unresolved pairings; workflow-config-per-stage diff until `PagesWorkflow.stages` read model
+  is completed (see `template-maintenance/PHASE0-FINDINGS.md` §2).
+
+## Success criteria
+
+1. A ticket's UAT changes are captured exactly and rendered as a review checklist (self-version). ✅
+2. Two templates diff correctly with pairing; unresolved pairings are escalated to a human + remembered. ✅ engine + cross-object path ready; interactive UX pending (eco-helpers).
+3. A reviewed delta deploys to PROD as WorkflowCommands, then is verified (ecoportal-qa) — no regressions.
+4. A template can be BUILT from a declarative spec via one ordered command batch. ✅ emitter ready; live characterization pending (sandbox creds).
+5. Monitoring shows which registers/subsets are sync-ready to their active template.

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,122 @@
 
 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.
+
+### Fixed
+
+- **LocationStructure query — `updatedAt` bare selection** → `Field must have selections (field
+  'updatedAt' returns DateTime but has no selections)`. `LocationStructureType.updatedAt` returns the
+  `DateTime` object (`{ dateTime, timeZone }`), so it must be selected with sub-fields. Fixed in
+  `Query::LocationStructure` and `Query::LocationStructure::Draft` (now `updatedAt { dateTime timeZone }`).
+  The plural `Query::LocationStructures` does not select it and was unaffected.
+  - **Root cause:** the bare selection has existed since 2023 (v0.3.x) but was **never exercised** —
+    no spec covered these queries, and the tagtree/users-sync path only began fetching the location
+    structure via GraphQL (rather than APIv2) as of the cutover, so it first ran in production.
+  - **Regression guard added:** `spec/.../query/location_structure_spec.rb` renders the query blocks
+    offline and asserts `updatedAt` carries `{ dateTime timeZone }` — this would have failed in CI.
+- **LocationDraft fragment — `createdAt` over-selection** (found by the full audit below): selected
+  `createdAt { dateTime }`, but `Draft.createdAt` is an `ISO8601DateTime` **scalar** → would throw
+  `Selections can't be made on scalars` whenever the location-structure **draft** query runs. Now bare
+  `createdAt`. Guarded by the same spec.
+
+### Added
+
+- **`tests/validate_queries.rb`** — offline audit: renders every gem query (auth stubbed, no network),
+  assembles its fragments, and validates the full document against a schema introspection JSON. Flags
+  the whole bug class — object fields selected bare ("must have selections") and scalars over-selected
+  ("selections can't be made on scalars"). A full run confirmed these two location fixes are the ONLY
+  such issues across all 17 query classes (contractors, actions, pages, register, templates: clean).
+
 ## [1.3.9] - 2026-07-02
 
 APIv2→GraphQL cutover hardening (backwards-compatible). Live-validated on the maintained ooze