ecoportal-api-graphql 1.3.9 → 1.3.11

data/docs/worklog.md

@@ -8,6 +8,414 @@ 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`,
+commit `19c1dea`, 8 specs, rubocop clean): two SAME-object snapshots (ids retained) → exact structural
+changelog (added/removed/changed/moved for stages/sections/fields[label,type,section-move]/options
+[label,weight]). `Diff::Change` is command-ready. This is a **shared gem capability** (admin/
+troubleshooting/integration/QA), not QA-only — per Oscar's clarification that these tools are the
+epicenter of admin+troubleshooting automation.
+
+**KEY FINDING — corrected a wrong doc claim:** `genomeSignature: String` **IS exposed** in the live
+GraphQL schema on `DataFieldsInterface` + every data-field type (verified in the schema dump). The old
+`graphql_domain_knowledge.md` claim "NOT exploitable" was wrong — corrected. Real gap: our gem doesn't
+REQUEST it (add to the data-field fragment). Genome stays a strong-but-fallible pairing signal.
+
+**Comprehensive harvestable knowledge doc:** `.ai-assistance/code/template_diff_pairing_domain.md` —
+captures Oscar's full brain-dump (UAT→PROD regression modes, no-stable-identity Mongo obstacle,
+self-version vs cross-object diff, genome verified facts + 6 failure modes, data-in-fields principle,
+equivalence-matching reframe + learning ledger, diff MODALITIES, layering, pipeline, Product context)
+so it never needs re-explaining and ep-ai-standards can harvest it. New project `template-diff-deploy`
+(INTENT+TODO). Confirmed with Oscar: equivalence reframe, self-version-first, ledger as first-class.
+
+**NEXT (template-diff-deploy):** add `genomeSignature` to fragment; `Change`→WorkflowCommands; pairing
+engine + ledger (eco-helpers, reuse `TypedFieldsPairing`); diff modalities; deploy+verify+monitor. Also
+tighten ecoportal-qa to use the gem's page-model (drop its own TemplateModel).
+
+---
+
+## ▶ SESSION 2026-07-03 — NEW tool: ecoportal-qa (QA-as-CI/CD, Phases 1–2 built, Phase 3 scoped)
+
+**Phase 3 SCOPED (docs only, branch `feature/qa-services-delivery-project`):** Jira adapter design in
+`qa-services-delivery/PHASE3-SCOPE.md` — the Jira channel is *just another consumer of the canonical
+Result* (no runner/DSL changes); `Jira::{Client,RestClient,McpClient,DryRunClient,Publisher}`;
+human-gated (report-only default, explicit `--transition`, never auto); redact-before-post + idempotent
+comments + audit. Decision (pending Oscar): interface + **REST-first**, MCP later (CI endgame likely
+lacks MCP). Sub-phase **3a (DryRunClient + Publisher) is unblocked** and can start before creds; 3b/3c
+need Jira project + token. Also added **`ROADMAP.md`** — north-star narrative (one Result → many
+channels; P1–P5 capability ladder; how each rung changes the human's day) written to make the
+vision→execution path legible for Oscar. Build blocked on 4 open Qs (Jira project/statuses, REST-vs-MCP,
+verdict field, where check-sets live).
+
+**Phase 2 done (branch `feature/phase-2`, commit `22cc865`, 31 specs green, rubocop clean):**
+CSV + HTML reporters (JSON/Text refactored to render from the canonical hash); `Redactor` PII scrub
+(preserves verdict/counts); `exe/ecoportal-qa` CLI (`run --source fixture:PATH|graphql:ID
+--format text|json|csv|html [--redact]`, exit code = verdict for CI); richer checks — negative
+assertions (stage/section/field absent), `label_pattern` regex, `field_count` (exact/`{min,max}`),
+`fields_in_order`/`sections_in_order`, select `option_weights`, top-level force presence/binding
+(skip when not captured). Synthetic `sample_template_page.json` fixture exercises them offline.
+**Only remaining Phase-2 item: live capture of `6a3fa5b8…622b` — BLOCKED on sandbox creds.**
+
+---
+
+New standalone repo **`ecoportal-qa`** (`C:\ruby_scripts\git\ecoportal-qa`, git-init'd, commit
+`1a62031`, v0.0.1) for the **Services Delivery QA team** who review **org config/template changes**
+against Jira tickets. **QA-as-CI/CD:** QA authors declarative check-sets (YAML DSL) → Ruby compiler →
+runnable checks → read-only runner → canonical Result JSON → reporting/Jira/monitoring.
+
+- Phase 1 built + green: `DSL::CheckSet`, `Compiler`, `TemplateModel`, `Source::{Fixture,Graphql}`
+  (GraphqlSource lazy/read-only), `Runner`, `Result` (verdict + honest `:skip`), `Reporters::{Json,Text}`.
+  Proven vs the real `toocs_coding_page.json` snapshot (7 pass / 2 fail / 3 skip). 11 specs, rubocop clean.
+  Core has NO runtime gem deps (doc-based) → offline-runnable.
+- **ep-ai-standards question resolved:** standards live in ep-ai-standards; implementations live with
+  their deps. `ecoportal-qa` is its own repo but ships a `.ai-assistance/` conformance stub
+  (`conformance.json`) so ep-ai-standards discovers/governs it without owning the code.
+- Project docs on gem branch **`feature/qa-services-delivery-project`** (UNMERGED):
+  `.ai-assistance/projects/qa-services-delivery/{INTENT,DECISIONS,TODO}.md`.
+- Drivers: safety/privacy/simplicity/delegation-to-QA/monitoring/reporting/governance, Ruby, human-in-loop.
+- Roadmap: P2 CSV/HTML reporters + more checks + capture `6a3fa5b8…622b`; P3 Jira adapter (human-gated,
+  MCP vs REST TBD); P4 CI-as-code "ticket as pipeline"; P5 opt-in governed auto-approve.
+
+**Merge note:** `ecoportal-qa` is a fresh standalone repo (no default-branch merge needed — it IS the
+main line there). Only the gem's `feature/qa-services-delivery-project` docs branch awaits merge to main.
+
+---
+
+## ▶ SESSION 2026-07-02 — Template pipeline + ooze-native foundations (4 branches, unmerged)
+
+Post-cutover, picked up **two** parallel threads at Oscar's direction: (3) ooze → native GraphQL
+migration — **native classes ONLY, no delegation flip yet** — and (4) the template-editing (CSV)
+pipeline. Grounded both against live code via two parallel Explore surveys before writing. All work
+is on feature branches, **green + rubocop-clean, unmerged**, pending Oscar's review + the merge plan
+below. Nothing touches `main`/`master` yet; all additions are pure/non-breaking (no case flipped, no
+shim removed, no existing API changed).
+
+**Key findings (corrected the design docs):**
+- A **template IS a page** — `Query::Templates` returns PageUnion; structure reads via the page
+  model. `Builder::Template` (create/update with `commands:`) + `executeWorkflowCommands` already
+  exist. So build-from-scratch is unblocked; only workflow-config *diff* waits on the partial
+  `PagesWorkflow.stages` read model.
+- **`placeholderId` is the id-threading primitive** — commands reference not-yet-created nodes
+  intra-batch by client-chosen placeholder; simpler than the location engine's `newId` remap.
+- **`build_commands` is non-idempotent** for key-renaming commands (addSelectFieldOption:
+  data_field_id→dataFieldId). Emitter output is FINAL built form, straight to the mutation.
+- Ooze: first-wave cutover cases (RegisterUpdateCase/TargetOozesUpdateCase) are **force-free**
+  (migratable now); forces live only in downstream training scripts. Native `Pages::Page::Base`
+  already gives the loop skeleton to build on.
+
+**Branches (all green, rubocop clean, UNMERGED):**
+| Repo | Branch | Contents | Base |
+|---|---|---|---|
+| gem | `feature/template-editing-pipeline` | `tests/dump_template_model.rb`, WorkflowCommand serialization spec (10 ex), `template-maintenance/PHASE0-FINDINGS.md` | main @03799f5 |
+| gem | `feature/ooze-native-phase0` | `ooze-graphql-native-migration/INVENTORY.md` + TODO scope note | main @03799f5 |
+| eco-helpers | `feature/ooze-graphql-native-migration` | `graphql/helpers/pages/{shortcuts,filters,rescuable}` + specs (37 ex) | master @5b9d7c07 |
+| eco-helpers | `feature/template-editing-pipeline` | `graphql/samples/pages/template/{command_emitter,base}` + spec (9 ex) | master @5b9d7c07 |
+
+**STRATEGIC MERGE PLAN (for Oscar to action):**
+1. **Gem first** (no cross-repo dep): merge `feature/ooze-native-phase0` (docs-only) then
+   `feature/template-editing-pipeline` into `main`. Independent; either order. No release bump
+   needed (tool + specs + docs; patch-level if tagging).
+2. **eco-helpers next** (depends only on the *released* gem v1.3.9, which ships the WorkflowCommand
+   contract — no gem changes are required by either eco-helpers branch): merge
+   `feature/ooze-graphql-native-migration` (pure helper additions) then
+   `feature/template-editing-pipeline` (samples additions) into `master`. Independent of each other.
+3. **Order rationale:** gem branches carry no runtime coupling to eco-helpers; eco-helpers branches
+   only reference the *already-released* gem constant `Input::WorkflowCommand` at runtime. So there
+   is **no hard merge-order dependency** — the split is by repo, and everything is additive.
+4. **Do NOT** merge as a case flip / shim removal — those stay `[ ]` in the ooze TODO until parity
+   is proven (unchanged by this session).
+
+**★ NEXT SESSION:**
+- Template Phase 2/3: extend the emitter (editStage/editFieldConfiguration/gauge stops), then the
+  **sandbox live characterization** — run `dump_template_model.rb` on `6a3fa5b8…622b`, replay via
+  Template::Base, assert structure-equivalence. Needs a sandbox org + creds (Open Q #1).
+- Ooze Phase 1/2: re-express `OozeHandlers#merge_values` + native `Creatable` against GraphQL
+  data-field types; then native `Register::Base` on top of `Pages::Page::Base`; A/B parity harness.
+- Still open from prior: FARMERS/Travis support (F1 simulate-noop, F2 stale-patchVer) — locate
+  `FARMERS_GRAPHQL_HANDOVER.md` (api-deprecation branch, likely training repo).
+
+---
+
 ## ▶ DEEP REVIEW (2026-06-30 late) — pre-live audit of TOOCS + CANS; 3 more fixes
 
 Exhaustive audit (4 parallel sub-investigations) of both prod dry-runs before going live.

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
 

data/lib/ecoportal/api/graphql/builder/template_builder.rb

@@ -0,0 +1,174 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Builder
+        # Build-from-scratch emitter for a template/workflow: turns a DECLARATIVE spec
+        # (stages -> sections -> fields -> options / config / gauge-stops) into an ordered batch of
+        # built `WorkflowCommand` hashes, ready for `Builder::Template#create(commands:)` /
+        # `#update(model, commands:)` (which wrap `executeWorkflowCommands`).
+        #
+        # This is the gem-level, reusable BUILD emitter (previously a one-off in eco-helpers samples).
+        # It shares ONE emission layer with the DIFF-DEPLOY pipeline: both produce an ordered
+        # `WorkflowCommand` batch, and both use the SAME `placeholderId` id-threading primitive that
+        # `Diff::CommandSynthesizer` uses — a newly-created node is addressed by a client-chosen
+        # `placeholderId`, and every later command in the same batch that references it substitutes
+        # that placeholder (the server has not assigned real ids yet). Here every node is brand new,
+        # so the whole batch is threaded through placeholders.
+        #
+        # SPEC SHAPE (all keys optional unless noted; only VALID command inputs are emitted):
+        #
+        #   {
+        #     stages: [
+        #       { name: 'Report', ordering: 0, sections: [        # addStage(name, ordering)
+        #         { layout: 'ONE_COLUMN', fields: [               # addSection(layout) + addStageSection
+        #           { field_type: 'PlainText', label: 'Description', column: 0,
+        #             description: 'ID:token' },   # addField (+ editFieldConfiguration for description)
+        #           { field_type: 'Select', label: 'Severity',
+        #             options: [ { label: 'Low', weight: 0 }, ... ],                # addSelectFieldOption
+        #             config: { select: { multiple: false } } },                   # editFieldConfiguration(byType:)
+        #           { field_type: 'Gauge', label: 'Risk',
+        #             stops: [ { threshold: 0, color: '#0f0' }, ... ],              # addGaugeFieldStop
+        #             config: { gauge: { max: 100.0 } } }
+        #         ] }
+        #       ] }
+        #     ]
+        #   }
+        #
+        # ORDER — addStage -> addSection -> addStageSection -> addField -> (addSelectFieldOption |
+        # addGaugeFieldStop | editFieldConfiguration). This is the dependency-safe order the workflow
+        # command bus expects; placeholderId resolution makes the intra-batch references valid.
+        #
+        # SAFETY — only keys present in each command input's VALID_KEYS are emitted (the input classes
+        # slice + compact). A spec key with no corresponding command input is dropped, not fabricated.
+        # `field_type` shape and per-type config (`byType`) are NOT invented: config is passed through
+        # under its byType sub-hash exactly as given (the caller supplies confirmed byType keys), and
+        # is emitted only for a field that carries one.
+        class TemplateBuilder
+          # @param spec [Hash] the declarative template spec (see class doc). String or symbol keys.
+          def initialize(spec)
+            @spec         = symbolize(spec || {})
+            @commands     = []
+            @counter      = 0
+            @built        = false
+          end
+
+          # Ordered Array of built command hashes ({ commandKey => input }), placeholder-threaded.
+          def commands
+            return @commands if @built
+
+            @built = true
+            build_all
+          end
+
+          # Ready to hand to `Builder::Template#create(commands: builder.to_commands)`.
+          alias_method :to_commands, :commands
+
+          def to_h
+            { commands: commands }
+          end
+
+          private
+
+          def build_all
+            Array(@spec[:stages]).each_with_index { |stage, idx| emit_stage(stage, idx) }
+            @commands
+          end
+
+          def emit_stage(stage, index)
+            stage_ph = placeholder(:stg)
+            add(:addStage, name: stage[:name], ordering: stage.fetch(:ordering, index), placeholderId: stage_ph)
+            Array(stage[:sections]).each { |section| emit_section(section, stage_ph) }
+          end
+
+          def emit_section(section, stage_ph)
+            section_ph = placeholder(:sec)
+            add(:addSection, layout: section[:layout], placeholderId: section_ph)
+            # Attach the freshly-created section to its (freshly-created) stage.
+            add(:addStageSection, stageId: stage_ph, sectionId: section_ph)
+            emit_section_heading(section, section_ph)
+            Array(section[:fields]).each { |field| emit_field(field, stage_ph, section_ph) }
+          end
+
+          # A section's heading is not an addSection input; set it via editSectionHeader after create.
+          def emit_section_heading(section, section_ph)
+            heading = section[:heading]
+            return if heading.nil?
+
+            add(:editSectionHeader, sectionId: section_ph, header: heading)
+          end
+
+          def emit_field(field, stage_ph, section_ph)
+            field_ph = placeholder(:fld)
+            add(:addField,
+                fieldType:     field[:field_type] || field[:fieldType],
+                label:         field[:label],
+                stageId:       stage_ph,
+                sectionId:     section_ph,
+                column:        field[:column],
+                placeholderId: field_ph)
+            emit_description(field, field_ph)
+            emit_options(field, field_ph)
+            emit_stops(field, field_ph)
+            emit_config(field, field_ph)
+          end
+
+          # A field's `description` is NOT an addField input (the schema's WorkflowAddFieldInput has
+          # no `description` key — VERIFIED against the 20260605 dump). It is a top-level key of
+          # editFieldConfiguration, so we persist it with a follow-up editFieldConfiguration
+          # addressed to the freshly-created field placeholder. Emitted only when supplied. This is
+          # the seam the CSV/hidden-field identity token rides on. NOTE: `required` has no schema
+          # input key at all, so it is intentionally NOT emitted (a spec `required:` is ignored).
+          def emit_description(field, field_ph)
+            description = field[:description]
+            return if description.nil?
+
+            add(:editFieldConfiguration, data_field_id: field_ph, description: description)
+          end
+
+          def emit_options(field, field_ph)
+            Array(field[:options]).each do |opt|
+              add(:addSelectFieldOption, data_field_id: field_ph, label: opt[:label], weight: opt[:weight])
+            end
+          end
+
+          def emit_stops(field, field_ph)
+            Array(field[:stops]).each do |stop|
+              add(:addGaugeFieldStop, data_field_id: field_ph, threshold: stop[:threshold], color: stop[:color])
+            end
+          end
+
+          # Per-type field configuration passed through under its byType sub-hash exactly as supplied
+          # (e.g. { select: { multiple: true } }, { gauge: { max: 100.0 } }). Emitted only when
+          # present; keys are validated/sliced by the EditFieldConfiguration input, never fabricated.
+          def emit_config(field, field_ph)
+            config = field[:config]
+            return if config.nil? || config.empty?
+
+            add(:editFieldConfiguration, data_field_id: field_ph, byType: symbolize(config))
+          end
+
+          # Build one command and append it. Reuses the SAME builder the diff synthesizer uses, so
+          # BUILD and DIFF-DEPLOY emit through one layer.
+          def add(command_key, **kwargs)
+            @commands << Ecoportal::API::GraphQL::Input::WorkflowCommand.build(command_key, **kwargs)
+          end
+
+          # A deterministic client-chosen placeholderId — the id-threading primitive shared with the
+          # diff synthesizer. Prefix marks the node kind for readability of the emitted batch.
+          def placeholder(prefix)
+            @counter += 1
+            "ph_#{prefix}_#{@counter}"
+          end
+
+          def symbolize(value)
+            case value
+            when Hash  then value.each_with_object({}) { |(k, v), h| h[k.to_sym] = symbolize(v) }
+            when Array then value.map { |e| symbolize(e) }
+            else value
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/builder.rb

@@ -1,16 +1,17 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Builder
-      end
-    end
-  end
-end
-
-require_relative 'builder/location_structure'
-require_relative 'builder/action'
-require_relative 'builder/contractor_entity'
-require_relative 'builder/register'
-require_relative 'builder/page'
-require_relative 'builder/kickstand'
-require_relative 'builder/template'
+module Ecoportal
+  module API
+    class GraphQL
+      module Builder
+      end
+    end
+  end
+end
+
+require_relative 'builder/location_structure'
+require_relative 'builder/action'
+require_relative 'builder/contractor_entity'
+require_relative 'builder/register'
+require_relative 'builder/page'
+require_relative 'builder/kickstand'
+require_relative 'builder/template'
+require_relative 'builder/template_builder'