ecoportal-api-graphql 1.3.13 → 1.3.16

data/docs/worklog.md

@@ -1,977 +0,0 @@
-# Worklog — ecoportal-api-graphql
-
-A rolling record of what has been done, what is in progress, and what comes next.
-Update before ending a session. Read from the bottom up to find the latest state.
-
-For per-project tracking (intent, decisions, upstream deps), see `.ai-assistance/projects/<slug>/`.
-This file tracks cross-project session state and the overall repo status.
-
----
-
-## ▶ SESSION 2026-07-10 — OD-001 decision-support delivered to ep-ai-standards (breadcrumb)
-
-Produced a decision-support doc mapping this repo's REAL GraphQL mutation surface onto
-ep-ai-standards' operation-class ladder for OD-001 (the GraphQL gateway PROD "low-risk"
-auto-approval threshold / provisional Dial A). Evidence-based from live introspection
-(`.ai-assistance/tmp/20260605T101224_live_ep_graphql_schema.graphql.json` -- 190 mutations)
-+ code-specs + `lib/ecoportal/api/graphql/mutation/**`. Key findings: register-type axis is
-real + in-schema (`Register.registerStatus: TESTING|LIVE`, `base/register.rb:7`); org-type
-(sandpit/uat/demo/PROD) is NOT a schema field (infra/credential-level, `base/organization.rb`
-exposes only id/name/companyName/logoUrl); several mutations do not map cleanly (payload-hidden
-deletions in `updatePage`, bulk/cascade, cross-env UAT->PROD deploy, egress/email/credential
-mints). Delivered to ep-ai-standards' bridge inbox as
-`ecoportal-api-graphql-od001-mutation-mapping.md` (STATUS: PENDING) -- a PROPOSAL for the graphql
-team + Oscar to validate via an ep-ai-standards MR. NO code changed in this repo. Does not change
-OD-001's ruling. (OD-007 breadcrumb convention.)
-
----
-
-## ▶ 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.
-Full detail + every hypothesis/verdict: `.ai-assistance/projects/ooze-graphql-native-migration/
-analysis/2026-06-30-cutover-workflow-deep-review.md`. Three real issues found & FIXED (gem only):
-1. **Number `""`→`0.0`** (`data_field/number.rb`) — `"".to_f` wrote a real 0.0 over the server
-   value for an empty CSV numeric cell. Now blank→nil. (Live-corruption footgun.)
-2. **People reader node-fallback** (`data_field/people.rb`) — read only `peopleIds`; if a read
-   ever returned it null while `people{id}` nodes were present, an append would WIPE. Now falls
-   back to the nodes (mirrors CrossReference). (Latent, hardened.)
-3. **CANS create dry-run mislabel** (`compat/pages.rb` + `interface/base_page.rb`) — a
-   buildFromTemplate draft carries a patchVer, so `new_draft?` (patchVer-nil) mis-previewed a
-   CREATE as an UPDATE. Now marked via `_compat_source_template_id` in `get_new`. (Display only.)
-Verified-correct (no change): People append preserves; Select all-options shape; PlainText clear;
-dirty baselines; CANS routing (no duplicate-create); the stageId guard breaks no other case.
-+20 specs incl. a fixture replay (`spec/.../integration/toocs_submit_replay_spec.rb`) that
-reproduces the EXACT observed TOOCS body and proves the stageId regression. New tool
-`tests/dump_page_model.rb` dumps a page model before/after a submit for fixtures.
-
-**FOLLOW-UP (2026-07-01) — …61 RESOLVED + Gauge fixed.** CANS field …61 `0.0` is a REAL zero:
-`STANDARD COST=0` (unquoted) in the CSV — not an artifact. Verified `Eco::CSV` (eco-helpers
-`lib/eco/csv.rb`): stdlib `::CSV`, no nil/empty override → unquoted empty→nil, quoted empty `""`→""
-(so quoted-empty numeric cells WOULD hit `"".to_f→0.0`; the blank→nil fix is the right net).
-**Gauge** had the identical `numeric&.to_f` footgun → fixed; Number+Gauge now share
-`DataField#numeric_or_nil` (can't drift). +6 Gauge specs. Suite 470/0/2 pending, rubocop clean.
-Remaining (non-blocking): created-CANS-pages-unsubmitted (parked); confirm 6a32…d7d=='Coding'.
-Farmers case audited (own note): `-simulate` is a no-op for GraphQL writes (can't dry-run-validate)
-+ stale-patchVer risk on multi-doc suppliers — see analysis doc.
-
----
-
-## ▶ RESOLVED (2026-06-30 late) — update+submit now carries `stageId` (full-cycle fix, gem-only)
-
-**FIXED — gem suite 445/0/2 pending, rubocop clean. Re-run TOOCS `-simulate` to confirm the
-body now shows `:stageId`, then it's safe to run live.** The fix is GEM-ONLY (eco-helpers
-unchanged — `OozeRedirect#stage` already builds the StageView; the gem now does the recording).
-
-**Root cause (confirmed end-to-end):** `OozeRedirect#stage` builds a `Compat::StageView` but the
-base OozeSamples loop **enqueues/updates the FULL page** (enqueue is first-wins by id — the
-StageView is never the queued object). `process_ooze` calls `target.submit!` on that full page,
-whose `current_stage_id` server-state inference returned nil → the operation nil-guard dropped
-`stageId`. The StageView (which knows its stage id) was discarded after the `with_stage` block.
-
-**Fix (3 parts, gem):**
-1. `Model::Page::Phased#_compat_active_stage_id` (new accessor) — `Compat::StageView#initialize`
-   records the viewed stage id on its `@page` (which IS the queued page, same object), so a later
-   `submit!`/`sign_off!` on that page can resolve the stage the work was done on.
-2. `Compat::Pages#compat_stage_id` resolves most-explicit-first: pinned `submit!(stage_id:)` →
-   `_compat_active_stage_id` (StageView) → `current_stage_id` (inference, last resort).
-3. `Input::Page::Update.from_model` **raises** when `submit`/`task` present but `stage_id` nil —
-   the platform invariant (people-field perms are stage-scoped; submit MUST name its stage).
-   +11 specs (stage_view records active stage; compat_stage_id order; guard raises/permits).
-   Captured in `.ai-assistance/code/ecoPortal_architecture/08_stages_sections.md` (why + mechanism).
-
-**Schema (verified):** `stageId` is a FIELD of `UpdatePageInput`, NOT a separate `updatePage(...)`
-arg. (Stale/wrong: `diff_as_input.md:224` flat-arg shape — fix later.)
-
-**Known limitation (non-blocking):** `Phased#current_stage_id` (server-state inference) can return
-nil / the wrong stage on multi-stage pages; it's now only a guarded last resort — prefer a stage
-view. The dry-run still prints only the input hash, not operationName + variables (Oscar steer;
-follow-up, not built).
-
-<details><summary>original blocker note (for history)</summary>
-
-**Do NOT run the TOOCS/ooze update+submit cases live until fixed.** During `-simulate` the
-act-gov TOOCS body came back **without `stageId`**:
-```
-{:id=>"6a32...aa8", :patchVer=>229, :submit=>true,
- :task=>{:completePageTask=>{:forcedComplete=>true}},
- :dataFields=>{:updates=>[{:people=>{...}}]}}   # ← no :stageId
-```
-
-**Schema settled (verified):** `stageId` is a FIELD of `UpdatePageInput` (the single
-`input: UpdatePageInput!` wrapper) — NOT a separate `updatePage(...)` argument. Sources agree:
-`ecoportal_schema_reference.md:90`, `schema_analysis.md:94`, `04_graphql_queries_mutations.md:144`,
-and the gem's own `mutation/page/update.rb:17`. So `from_model` is right to nest `stageId` inside
-the input. (Stale/contradicting: `diff_as_input.md:224` shows an old flat-arg shape — wrong, fix later.)
-
-**Root cause:** `Model::Page::Phased#current_stage_id` (phased.rb:25) returned **nil** for this page
-→ `compat_stage_id` nil → `from_model`'s nil-guard (`input[k]=v unless v.nil?`) dropped `stageId`.
-`current_stage_id` matches `state=='inprogress' || active==true` in `doc['stagesIndex']||doc['stages']`;
-the `CommonPageUnion` get path apparently doesn't yield a matching stage. The 2026-06-29 "stage
-advanced" confirmation was the **create** path (top-level `stageId`) — the **update+submit** path
-was never exercised, so this is a real, untested gap. `08_stages_sections.md:59` warns a submit
-without `stageId` may not associate with the right stage → unsafe on prod.
-
-**Fix (agreed direction, NOT yet built):**
-1. **Hard guard** — `from_model`/`compat_submit_kargs` must RAISE when `submit: true` (or a `task`)
-   is present but `stageId` is nil. Never send a submit without its stage. (Definitely correct.)
-2. **Resolution** — make `current_stage_id` actually resolve on the update path. Resolution
-   approach parked pending diagnosis (see note below). Candidates: fix the `doc['stages']` state
-   match, fetch `currentStage`/`PhasedPageFields` in the compat get query, or pin `stage_id` in the case.
-
-**NOTE (Oscar steer):** the dry-run feedback currently `pp`s only the `input` hash. To diagnose
-this (and make the preview faithful) it should print the **full GraphQL request** — `operationName`
-+ the **variables** actually sent — not just the input sub-tree. Noted as a follow-up; not built yet.
-
-</details>
-
----
-
-## ▶ START HERE TOMORROW (2026-07-01 — LAST cutover day)
-
-Branch `fix/ooze-redirect-faithful-dryrun` (gem + eco-helpers), all UNCOMMITTED.
-
-**Confirmed working on live act-gov (2026-06-30 end):** TOOCS dry-run now prints the faithful
-body and is CLEAN — `dataFields.updates` = ONLY the People field (`Coding completed by`):
-```
-:dataFields=>{:updates=>[{:people=>{:id=>"6a3225522b97b00073c22cea",
-                                     :peopleIds=>["65d6d3dcacb0b3000773f547"]}}]}}
-```
-No phantom empty `crossReference` clears (CrossReference set-based `dirty?` fix works);
-Breakdown Agency correctly omitted (already coded on the page = code 8422). People write-path
-good. `submit: true` + `forcedComplete` ride along as expected.
-
-**Do, in order:**
-1. **Re-confirm CANS** `-simulate` (jamestrong) — expect the create body (templateId +
-   PlainText/Number/Select updates) still clean. (Last seen good before the CrossReference fix;
-   re-run to be sure nothing regressed.)
-2. **Commit** the branch in both repos (only after the above looks right). Changes:
-   - gem: `compat/pages.rb` (faithful dry-run body), `base/page/data_field/cross_reference.rb`
-     (set-based dirty vs `original_doc`), specs (`compat/pages_spec`, `model/page/phased_spec`,
-     `base/page/data_field_spec`), `.ai-assistance/projects/ooze-graphql-native-migration/`,
-     this worklog + `.ai-assistance/code/refactoring/datafield-readwrite-shape-asymmetry.md`.
-   - eco-helpers: `ooze_samples/ooze_base_case.rb` (affirmative `[dry-run] would create/update`
-     line) + the earlier shim slimming (`ooze_redirect.rb`, `register_update_case.rb`).
-   - implementation: `toocs_coding_case.rb` already reverted clean (diagnostic removed) — no commit needed there.
-   - Full gem suite green: 434 examples, 0 failures, 2 pending. Rubocop clean on touched files.
-3. **Parity runs** — the real 1-Jul validation: wire the CANS/TOOCS A/B harness
-   (see [[project-parity-test-plan]]) and run the 3 prod use cases on GraphQL.
-
-**Optional / non-blocking:**
-- Tidy: `page.sourceTemplateId` → `page.source_template_id` at BOTH call sites in
-  `compat/pages.rb` (`create` + `create_body`) if house style prefers snake (not a rubocop
-  offense — calls aren't flagged; SnakeCamelAccess is snake→camel one-way).
-- The OPEN REVIEW below (DataField shape asymmetry: File/Image/Contractor) — separate, not a blocker.
-
----
-
-## ▶ OPEN REVIEW (2026-06-30) — DataField read/write shape asymmetry (flagged for thorough review)
-
-A real bug found+fixed on `CrossReference` (it was READ from `references.nodes` but WRITTEN to
-`pages`; a custom `dirty?` I'd hand-rolled wrongly baselined on `doc` instead of `original_doc`).
-Audit shows the SAME read≠write asymmetry on **FileField, ImageGallery, ContractorEntities**
-(broken readers + phantom-dirty; pre-existing) and mildly on TagField. NOT a 1-Jul blocker
-(cutover cases don't hit them), but needs a dedicated pass. Full audit + fix direction + a retro
-on why it slipped: `.ai-assistance/code/refactoring/datafield-readwrite-shape-asymmetry.md`.
-Key guardrail: never compute a dirty baseline from `doc` — use `original_doc`/`DiffService`; add
-`consolidate!`-cycle specs to every staged-write field.
-
----
-
-## ▶ HANDOFF (2026-06-29) — lint clean; stage-advance reframed; SCIM + new projects
-
-### Done this session
-- **Gem RuboCop clean** — 0 offenses / 526 files (commit `b3c6139` on `pages`). Safe
-  autocorrect + targeted code fixes + scoped `.rubocop.yml` relaxations for intentional
-  public-interface patterns (`id`/`ids`/`clientMutationId` AllowedNames; OneClassPerFile/
-  FileName/ToEnumArguments excludes). Adding `id`/`ids` centrally let RuboCop strip 17
-  now-redundant inline disables. (To run rubocop here: `bundle config set --local
-  local.graphql-client <path>` + `local.graphlient <path>` — rubygems.org index fetch fails
-  under the SSL inspection, so local git overrides are required. Stored in gitignored `.bundle/config`.)
-- **Training repo branch move** — `C:/ruby_scripts/implementation/training` had 21 unpushed
-  commits + uncommitted changes on `master`. Moved to new branch **`api-deprecation`**
-  (HEAD `ab312a4`); `master` reset to `origin/master` (`c4984db`). Uncommitted changes
-  (token-budget.json, settings.json, CLAUDE.md, untracked scripts/) carried to api-deprecation,
-  left uncommitted (machine-local — dev to commit). Recovery: `git branch -f master ab312a4`.
-
-### Stage-advance — RESOLVED ✅ (gem submit was correct; old call shape was wrong)
-**Live-confirmed 2026-06-29** (new test `compat_v2/page/submit_signoff_on_create`: 5/5 PASS,
-incl. "stage advanced after submit + sign-off"). Root cause: the stage has a **review-task
-config**, so `completePageTask` alone (the old `stage_submit` call, no `submit:`, no inline
-sign-off) just enters "reviewing" and never advances. The single call that advances:
-`updatePage(submit: true, task: { completePageTask: { signOff: true } })`. Backend logic
-(persisted `.graphql` ops + `app/services/new_ep/tasks/workflow.rb`) verified the inline
-sign-off auto-approves the review in the same call. NOT a missing-field issue (validation
-would surface as `success? == false`; the gem selects `errors` and `Logic::Payload#success?`
-honours it). See memory `page-stage-submission` for the authoritative logic.
-- **Gem change (commit pending, `pages`):** `Input::Page::Update.from_model`'s
-  `complete_page_task:` now accepts a Hash → `{ completePageTask: { signOff:, forcedComplete:,
-  notes: } }`. The throwaway page id is per-run (printed `page=<id>` at the assertion).
-
-### Next steps
-1. **Stage-advance — DONE** (see above). Optional follow-up: switch the old `stage_submit`
-   test to the confirmed `submit: true, complete_page_task: { sign_off: true }` call so it also
-   goes green (currently left as the no-submit diagnostic). Dev's call.
-2. **Backend persisted-query investigation — DONE** (Explore agent, 2026-06-29). Authoritative
-   submit/sign-off logic captured in memory `page-stage-submission`; SCIM Users endpoint in
-   `project-scim-users-apiv0-adapter`.
-3. **NEW test — DONE & PASSING live:** `compat_v2/page/submit_signoff_on_create` (create →
-   fill required + location → `submit: true` + inline `completePageTask { signOff: true }` →
-   stage advances). Shared helpers extracted to `mini/automated-tests/lib/page_stage_helpers.rb`.
-4. **NEW project — SCIM Users → APIv0 adapter (URGENT):** APIv0 (People) decommissioned 1 Jul
-   2026 (ext. to ~31 Jul). Need: list SCIM Users + adapter mapping SCIM model → legacy APIv0
-   People model for 2-3 maintained customer integrations + some Pages use cases. See memory
-   `project-scim-users-apiv0-adapter`.
-5. **NEW project — Azure Gallery App:** Entra/Azure AD gallery app to shorten customer SCIM
-   setup; possibly VS/.NET; reuse Oscar's old abandoned repos. Not started. See memory
-   `project-azure-gallery-app`.
-6. Carried-over: gem RSpec regression specs (8.6) for the 12 cutover fixes (offline); push
-   `pages` + `api-deprecation`; snake/camel access revisit + specs (memory `project-snake-camel-access`).
-
----
-
-## ▶ HANDOFF (2026-06-28, late) — cutover write/submit path; ONE open item: stage advance
-
-The mini `automated-tests` harness now covers read + ALL field-type writes + structure +
-stage-write + page-location, **27/28 green**. **12 gem bugs** found & fixed against live
-(see the 2026-06-28 entry below + commits). Tests are now **fresh/isolated** (each run uses
-~2 throwaway pages via `AutomatedTest.shared_page_id` + stage_submit's own). Cutover
-gem/integration surface is essentially done.
-
-### THE ONE OPEN ITEM — stage submit doesn't advance the stage
-`compat_v2/page/stage_submit`: location persists ✓, required fields filled ✓, `updatePage`
-returns OK ✓, but the stage does **not** transition (before==after). Investigation so far:
-- Schema (`.ai-assistance/tmp/20260605T101224_live_ep_graphql_schema.graphql.json`): there is
-  **no dedicated submit mutation**. Stage submit goes via `updatePage` `TaskInput` →
-  `completePageTask` (`CompletePageInput { forcedComplete, signOff, notes }`) or `reviewPageTask`.
-- `submit: true` + `completePageTask` together → OK but no advance (submit seems to just save
-  + shadow the task). Latest attempt (commit `ab312a4`): **`completePageTask` ALONE** (no
-  submit:true). **Needs a live re-run to confirm.**
-- If still no advance, next levers: `task: { completePageTask: { forcedComplete: true } }`;
-  or **get the exact submit call from Insomnia / browser network tab** (dev has it) — that's
-  the authoritative answer. The stage may also need its **activeTask id**, or stage 1's task
-  may be a review task (reviewPageTask). The test logs `page=<id>` on the failing assertion
-  for UI inspection.
-
-### State / branches (all UNPUSHED)
-- gem `pages` ~40 ahead; multi_org_api `api-deprecation` (farmers OozeRedirect); eco-helpers
-  `master` (`988bf1be` process_ooze stage_id + the pre-existing field_patches.rb change).
-- Cutover scorecard (memory `project-apiv2-cutover-usecases`): P0.1 farmers ✓, P0.3 phased
-  write-path ✓ (live), P1.4 get_by_name(type:) ✓, P1.5 filters ✓, P1.7 submit (plumbing ✓,
-  stage-advance OPEN). Remaining non-gem: P0.2 release/pin `pages` (dev), P1.6 cans membranes
-  dedup (customer script).
-
-### Next session
-1. Re-run `-mini -automated-tests`; if stage_submit still fails, resolve the submit-advance
-   (forcedComplete, or the real call from Insomnia) — last cutover thread.
-2. `bundle exec rspec` (offline regression specs); push the three branches.
-3. Optional: retire the now-optional `-automated-tests-setup` seeder; update
-   `mini/automated-tests/CLAUDE.md` for the fresh-per-test convention. Then CSV-300 (Group 9.3).
-
----
-
-## 2026-06-28 — page-read/create path validated against live; 8 bugs fixed; dispatch suite GREEN
-
-The mini `automated-tests` harness was run end-to-end against the live Mini org for the
-first time and flushed out **8 sequential bugs in the page create/read path** — which had
-clearly never been exercised against the API on the `pages` branch. All fixed; the
-`compat_v2/fields/dispatch` proof (OozeRedirect v2 `===` on real field instances for
-PlainText/Number/Select/People/CrossReference + Select read methods) now passes.
-**Final: 13 passed, 0 failed, 0 skipped.**
-
-### Bugs fixed (all on `pages`)
-1. `376b08d` — `CommonPageUnion` fragment **name casing** (registered `:CommonPageUnion`,
-   defined `commonPageUnion`) → server rejected every page read.
-2. `856454d` — bare **`DateTime` selections** (`createdAt/updatedAt/archivedAt`) needed
-   `{ dateTime }` (PageFields confirmed live; location_draft + pages_workflow same pattern).
-3. `3f0c2d5` — `CommonPageUnion` **directive vars undeclared**; restored per-op defaults
-   (`$content/$only_content/$fields`) via graphlient string-type defaults; Query::Page +
-   BuildFromTemplate default block → CommonPageUnion.
-4. `974cd31` — **`PageUnion` module→class** (v2 `resolve_class` matches `when Class`; a
-   Module fell through to "Unknown class").
-5. `264e47c` — compat **`create` omitted required `dataFields`** (non-null input).
-6. `f4acf67` — `Query::Page`/`Query::Pages` missing **`base_path 'currentOrganization'`**
-   (response nests under currentOrganization; direct instantiation by Compat::Pages dug
-   `data.page` → "Complete failure on request. Path: [\"page\"]").
-7. `f4acf67` — `corePageData` missing page-level **`__typename`** → PageUnion couldn't
-   dispatch Phased/Basic, fell back to Interface::BasePage.
-8. `4e1e673` — **phased read-compat flatten**: `Model::Page::Phased` overrides
-   `raw_data_fields`/`raw_sections` to flatten stages→sections→fields (dedup by id), so
-   `page.components`/`page.sections` work v2-style. field_collection stays the single
-   source (write path reuses it; mutations forward via shared doc refs).
-
-Each fix was diagnosed against code/JSON and, where possible, verified offline (module-vs-
-class resolution, graphlient variable-default emission, flatten dedup against the real
-response shape) before the live re-run — to cut the one-bug-per-round-trip loop.
-
-### Known follow-ups (compat layer — not blocking the dispatch proof)
-- **Section identity:** `sectionUnion` fragment fetches no section `id` → `page.sections`
-  can't dedup (only `heading`). Small fix: add `id` to the fragment.
-- **Write/collection review:** single-element mutations forward via shared refs; collection
-  ops (add/remove/reorder, multi-section identity) need review.
-- **Orphaned elements — clarified by dev 2026-06-28 (corrects an earlier overstatement):**
-  distinguish the *backend data model* from the *GraphQL-exposed model*. The GraphQL Page
-  **render** (stages→sections→fields) doesn't expose orphaned fields (no section) or sections
-  (no stage) — a property of the render, not proof orphaned data can't exist server-side. The
-  GraphQL Page type *may* later add flat `dataFields`/`sections`/`stages` accessors as core
-  (we suggested it); not done. Orphaned exposure is doubtful and, if added, would use this same
-  aliasing. ⇒ our flatten-from-stages covers everything the render exposes today; no
-  orphaned-fetch work is actionable (the render doesn't return them). (`CommonPageUnion` also
-  lacks `... on BasicPage { sections }`; revisit when basic-page reads are exercised.)
-
-### Harness (training repo) commits this run
-`974cd31`-era fixes to the seeder: Compat::Pages 2-step `get_new`+`create` (not Builder),
-`_seed` template/register ids in `fixtures.json`, layered committed-base + gitignored
-`fixtures.local.json`, graphlient fork path-mount in training Gemfile, connectivity test
-issues a real `templates` query (not proxy-class attrs).
-
-### Update (same day) — WRITE path validated; +1 bug; harness extended
-- **WRITE/update path GREEN.** Field value round-trip (`compat_v2/fields/values`, TODO 8.1)
-  passes live: get → set value → `pages.update` → re-read → persisted, for **PlainText,
-  Number, and Select**. First successful `updatePage` through the compat layer.
-- **Bug #9 (`652cbc9`):** `CommonPageUnion` didn't fetch `patchVer`; compat-read pages had
-  `patchVer=nil` → couldn't update. Added it to `corePageData`. (Tally now **9 bugs**.)
-- Also done: section `id` in `sectionUnion` + `raw_sections` dedup (`7237374`) + a
-  `compat_v2/page/structure` sections test (green); probe retired (training `edca4bf`);
-  Group 8 next-steps logged (`3faa0a3`); `origin/pages` duplicate handoff commit merged
-  clean (`0477f80`). Suite: **20 checks, all green** (after a test-only Number Float-compare fix).
-- values test extended with **People (`people_ids=`) + CrossReference (`page_ids=`)**
-  round-trips, fixture-gated (SKIP until `person_id` / `crossref_target_page_id` set in
-  `fixtures.local.json`) — these exercise the array-field write path + the known-missing
-  compat DSL when enabled.
-
-### Next
-- **8.1 finish:** supply a `person_id` + `crossref_target_page_id` fixture to validate the
-  People/CrossReference writes (may expose dirty-tracking gaps on the array setters).
-- **8.2** `submit!` / stage completion (note: advances the seeded page's stage — use a
-  throwaway page or be deliberate). **8.3** search filters. **8.6** gem RSpec regression
-  specs for the 9 fixes (pure offline). See migration TODO Group 8.
-
----
-
-## 2026-06-27 — graphql-client revival branch built, pushed, wired into this gem
-
-Migration TODO **7.1** closed. See `.ai-assistance/projects/api-v2-to-graphql-migration/`
-(TODO.md 7.1, UPSTREAM.md graphql-client section).
-
-### Done
-- **`integration/revival` branch on `rellampec/graphql-client`** — combines all four open
-  upstream PRs into one buildable ref. Built off `master` by cherry-picking the *unique
-  content* of each PR in clean order (#79 hygiene → #80 docs → #81 char-tests → #82 parse
-  fix) plus a single `ci: pin i18n` commit (each PR branch carried an identical copy).
-  Applying #79 before #80 avoided the known 1-line CHANGELOG conflict. **Pushed.**
-  Suite **green**: 176 runs, 0 failures, 0 errors, 4 skips; rubocop clean (61 files).
-- **Gemfile override (commit `8827b2f`)** — graphql-client forced to the fork branch in
-  `ecoportal-api-graphql`'s Gemfile, mirroring the existing graphlient override. Rationale:
-  gemspecs can't carry git sources, and graphlient (which pulls graphql-client transitively)
-  is a public gem we can't fork-point — so the override lives in the highest Gemfile we
-  control. Reversible; remove once the parse fix ships upstream.
-- Migration **TODO Group 7** added earlier today (commit `c8d36bc`): 7.1 (this) + 7.2
-  (portable `mini/automated-tests/` harness in the training repo — not yet started).
-
-### Blocked — needs the developer (agent sandbox network)
-- **`bundle install` could not complete here** — rubygems.org TLS interception (same block as
-  `live.ecoportal.com`); the git source itself fetched fine. Run in your shell:
-  ```
-  bundle install            # regenerates Gemfile.lock with the fork branch
-  bundle exec rspec         # confirm resolution + green
-  ```
-
-### Also done — TODO 7.2: portable `mini/automated-tests/` harness (training repo)
-- Built a self-contained, env-portable regression suite in the **training repo** at
-  `mini/automated-tests/`: assertion harness (`lib/asserter.rb`, `lib/test.rb` w/ auto-registry,
-  `lib/fixtures.rb`), a runner CLI `-automated-tests` (`automated_tests_case.rb`; `-list`/`-only`/
-  `-page-id`/`-fixtures`), and two seed tests (`org_read_test.rb`, `field_dispatch_test.rb` — the
-  assertion-based evolution of `gql_read_probe_case.rb`). Wired via one line in
-  `mini/config/session.rb`. Portability: org-specifics live only in `fixtures.json` (org_id
-  pinned by `-mini`); copy folder → edit fixtures → add the session.rb line to target another org.
-- **Verified offline** (harness wiring green via mock-graphql driver; all files `ruby -c` clean).
-  Live run is yours: `ruby main.rb -mini -automated-tests -page-id <all-21-fields template page id>`.
-  Folder doc: `mini/automated-tests/CLAUDE.md`.
-- **Refined per dev feedback + committed** (training `master`):
-  - **Area structure** (RSpec-style; folder mirrors namespace mirrors label):
-    `tests/connectivity/org_read`, `tests/compat_v2/fields/dispatch`, `tests/pages/` reserved.
-    `-only` is prefix-aware (`-only compat_v2` runs the subtree); recursive loader.
-    Commit `e7949ac`.
-  - **Readiness + seed tooling** (`-automated-tests-setup`): read-only readiness check
-    (verifies `fixtures.json` resolves) + opt-in idempotent seeder (`-seed`, dry-run unless
-    `-commit`). `ensure_page` via `create_from_template` (gem-verified input shape);
-    `ensure_register` best-effort. **Template creation stays manual** — gem wraps it
-    (`Builder::Template#create(commands:)`) but authoring the WorkflowCommandInput array is
-    the unsolved part (`project-template-update-architecture`). Commit `2fcacdb`.
-    Live `-commit` write path UNVERIFIED from sandbox (TLS) — dev confirms payload shapes.
-  - Confirmed: `gql_read_probe_case.rb` is superseded (dispatch → `compat_v2/fields/dispatch`,
-    auth → `connectivity/org_read`); retire it once the suite is green live.
-
----
-
-## 2026-06-26 — OozeRedirect validation + training-repo proof-test docs
-
-Resuming the **APIv2-cutover** front (top priority, deadline **1 Jul 2026**). Full detail
-in memory `project-apiv2-cutover-usecases` (updated today). Pick up here.
-
-### Done today
-- **OozeRedirect smoke-tested offline** (no live API) against the `pages`-branch gem (1.3.8)
-  via the training-repo bundle. Result: compat layer is **structurally sound** — all
-  constants resolve, `FieldPatches.apply!` clean, all compat methods land, and the v2 `===`
-  patch correctly matches GraphQL instances for all 5 mapped types. Two defects found:
-  - 🔴 **BLOCKER:** released `ecoportal-api-graphql 1.3.4` (what eco-helpers loads in its OWN
-    bundle) has **no `base/page/` layer at all** — Pages/DataField is unreleased (`pages`
-    branch only). Against 1.3.4 every patch **silently no-ops** (`safe_const` swallows
-    NameError) → use cases die with NoMethodError at runtime. **Releasing / pinning the
-    `pages` branch is a hard prerequisite for the cutover.**
-  - 🟢 **FIXED (uncommitted):** `OozeRedirect::FieldPatches Select#deselect` called
-    `mark_dirty!` (exists nowhere) → NoMethodError. Removed it; verified the in-place
-    `doc['options']` mutation is already caught by `DataField#dirty?` (LeafDiffService).
-    Change is in **eco-helpers** `lib/eco/api/usecases/graphql/compat/ooze_redirect/field_patches.rb`.
-- **Read-only proof case built** in the training repo: `mini/config/graphql_cases/gql_read_probe_case.rb`
-  (CLI `-gql-read-probe`, optional `-page-id`). Reads currentOrganization → `pages.get(id)`
-  → `FieldPatches.apply!` → asserts v2 `===` dispatch on REAL fields. **Zero writes.**
-  Verified it boots end-to-end (loads, registers command, builds GraphQL client onto the
-  live mini endpoint, reaches auth).
-- **Docs (per user):** training `CLAUDE.md` reframed as the proving ground (proof tests =
-  committed, not gitignored); new `mini/CLAUDE.md` (Mini Testing Site = test org on the
-  PROD platform `live.ecoportal.com`, org_id `59263deaed164b0019b1613d`); new
-  `graphql_cases/CLAUDE.md` (proof-test convention + the probe documented).
-
-### Blocked — needs the developer
-- **Live `mini` read run can't run from the agent sandbox** — TLS to `live.ecoportal.com`
-  fails `certificate verify failed` even with sandbox disabled + good CA bundle (network-layer
-  interception in the agent env, NOT a CA problem on this machine). **Run it in your own
-  shell** (`!` prefix so output lands here):
-  ```
-  cd C:/ruby_scripts/implementation/training; $env:ENVIRO_CONTEXT='local'; $env:LOCAL_REPOS='C:/ruby_scripts/git'
-  ruby main.rb -mini -gql-read-probe                  # auth smoke
-  ruby main.rb -mini -gql-read-probe -page-id <ID>    # full dispatch test (need a page-id from the all-21-fields template)
-  ```
-  (If `already activated rake 13.4.2 … requires 13.3.1` appears, use `bundle exec ruby …`.)
-
-### Uncommitted working-tree state (nothing committed today — awaiting your call)
-- **eco-helpers:** `field_patches.rb` (the `mark_dirty!` fix).
-- **training:** `CLAUDE.md` (M), `mini/CLAUDE.md` (new), `graphql_cases/CLAUDE.md` (new),
-  `gql_read_probe_case.rb` (new). All parse clean.
-- **ecoportal-api-graphql (this repo):** only this worklog edit.
-
-### Next (resume order)
-1. You run the probe in your shell + paste output (with a page-id) → closes OozeRedirect
-   validation on real data.
-2. Commit: eco-helpers fix; training docs+probe (ask before committing).
-3. Decide the **`pages` branch release/pin** (the blocker) — without it the cutover can't run.
-4. Then the still-open cutover items: **cans dedup** rework, **farmers/supplier_documents**
-   (Custom::UseCase) treatment. See `project-apiv2-cutover-usecases`.
-
----
-
-## ▶ CRITICAL — HOLIDAY HANDOFF (2026-06-16, dev away from 2026-06-17)
-
-Detailed state in memory `session-handoff-graphql-client-revival`, `page-stage-submission`,
-`graphlient-error-masking`, `project-template-update-architecture`. Three fronts:
-
-### ✅ Code is PUSHED — remaining actions are light
-- **graphlient** `C:\ruby_scripts\git\graphlient`, PR **#116** branch `feature/directives-dsl-support` is PUSHED (origin = `b621655`): unify inline fragments under `spread(on:)` (`spread :Name` / `spread on: :Type {}` / `spread on: :Type`; standalone `on` removed) + ostruct/mutex_m test-load fix + rubocop. **rspec + rubocop CLEAN.** REMAINING: post the @dblock reply (drafted in memory `session-handoff-graphql-client-revival`: "ready for re-review", explains the unify-under-`spread` decision + co-maintainer thanks) → await re-review.
-- **ecoportal-api-graphql** branch `pages` is PUSHED through `7c45b0f` (origin/pages): `bafbf80` B3 (require all 12 field_config byType modules), `837901e` docs, `7c45b0f` stage submit/close-out via updatePage `task` input (see memory `page-stage-submission`). Only this worklog commit is local-ahead → push when convenient (docs only).
-
-### 🟠 graphql-client PRs — OPEN, awaiting maintainer
-- **#79** hygiene → **#80** docs (stacked on #79) + **#81** characterization tests + **#82** parse-robustness fix (anchored regex; rspec+rubocop clean). All blocked only on a `github-community-projects` maintainer approving the CI workflow run (first-time-contributor gate).
-- **After #79 merges:** rebase #80 onto `upstream/master` + force-push (esp. if #79 is squash-merged) so #80 collapses to just its docs diff (resolve the 1-line CHANGELOG conflict).
-- #76 issue: developer already updated it. Keep OPEN until #82 ships.
-
-### 🟡 PARKED (non-critical, logged for later)
-- graphlient **error-masking** fix — `ClientError` drops `inner_exception` (`client.rb:19/41`); fix = `ClientError.new(e.message, e)`. Own PR. See `graphlient-error-masking` (user recalls patching BOTH gems).
-- ecoportal **`updateRelatedPage`** mutation gap (only genuine structural template omission; additive — see refactoring log).
-- Refresh **stale docs** `diff_as_input.md` + `diff_service_deep_dive.md` (describe pre-v1.3.8 behaviour).
-- **eco-helpers template-edit UX** — ship Sketch B (`graphql.template.edit` typed DSL); A (mutating read-model) later. See `project-template-update-architecture`.
-- **Template meta-language** decision: declarative diffable text vs imperative command bus — either needs a diff→`WorkflowCommandInput` compiler (the real work). Record in a DECISIONS log if pursued.
-
----
-
-## 2026-06-13 — fork revival kickoff (graphlient #115 confirmed; upstream ai-assistance deployed)
-
-### Done
-
-- **Migration TODO 1.2 closed** — graphlient DSL-only mode (`to_query_string` + `spread`) is
-  **already merged** into `ashkan18/graphlient` master as **PR #115** (verified via
-  `git ls-remote upstream`). NOT yet released → still ours to change (we authored it).
-- **Upstream-clone AI context deployed (local-only, verified non-leaking):**
-  - `graphlient/CLAUDE.md` rewritten (was truncated) with role + hard guardrails; already
-    gitignored upstream.
-  - `graphql-client/CLAUDE.md` created; excluded via `.git/info/exclude` (NOT tracked
-    `.gitignore`).
-  - `.ai-assistance/README.md` pointer added to each clone, excluded via `.git/info/exclude`.
-  - `git status` clean in both clones — confirmed none of it is visible to git.
-- **Deprecation research (background agent, primary sources):** gems are healthier than assumed.
-  graphql-client actively released (0.26.0, 2025-05-29), community-stewarded not abandoned;
-  graphlient low-velocity but active master. No evidence of major-org migration off them.
-  ecoPortal's CI/CD removal was internal, not an industry trend. → revival is realistic.
-
-### Blocked
-
-- **Global permission allowlist for the upstream clones** — the auto-mode safety classifier
-  **denied** writing `permissions.allow` to `~/.claude/settings.json` (won't let the agent
-  self-authorize permission rules). Developer must paste the block manually (provided in chat).
-  Until then, running specs/git in the sibling clones will still prompt.
-
-### graphql-client revival — progress (local, unpushed)
-
-- **(1) Hygiene PR — DONE locally.** Branch `chore/add-changelog-contributing` off `upstream/master`
-  (1 commit): `CHANGELOG.md` (reconstructed from merged PRs/tags back to 0.23.0; #60 correctly
-  placed under Unreleased, not 0.26.0) + `CONTRIBUTING.md` (Minitest flow).
-- **(2) Characterization specs — DONE locally, green.** Branch `test/parse-fragment-characterization`
-  off `upstream/master` (1 commit): `test/test_parse_fragment_characterization.rb` — 3 tests /
-  18 assertions pinning inline-named-fragment resolution, transitive local fragments, and
-  `source_document` vs sliced `document`. Built from a background-agent analysis that confirmed
-  the fix hinges on the `str.match(/fragment\s*#{const_name}/)` heuristic at `client.rb:161`.
-- **(3) Parse-level inline-fragment fix — NOT STARTED** (behavior-changing; design in
-  `project-graphql-client-redesign`). Must preserve the 6 characterized behaviors + fix the
-  prefix-collision edge by anchoring to `fragment\s+Name\s+on\b`.
-
-### Env blocker
-
-- **`bundle install` fails in-sandbox** (SSL cert verification to rubygems.org → `erubi ~> 1.6`
-  unresolved). Worked around by running the new test via system `graphql` gem directly
-  (`ruby -Ilib -Itest`). Full bundler-locked suite + RuboCop must run in CI (needs push) or with
-  sandbox disabled for `bundle install`.
-
-### Open Questions
-
-- None.
-
----
-
-## 2026-06-10 — ep-ai-standards deployments (token logging, lock protocol, policies)
-
-### Done
-
-- **Token budget logging** deployed: `token-logger.js` (Stop hook), `token-session-start.js`
-  (SessionStart hook), `token-report.ts` (cross-project weekly report). `.ai-assistance/token-budget.json`
-  set to priority=medium. `.claude/settings.json` hooks wired. `.ai-assistance/local/` gitignored.
-
-- **Cross-repo locking** deployed: `lock-multi.sh` (atomic multi-repo lock with estimated_release
-  + stale cleanup), `lock-queue.sh` (priority turn-request queue in `bridge/queue/`),
-  `.ai-assistance/version.json` (feature detection).
-
-- **`corporate-policies` skill** v1.0 deployed — 13 directives with ecoPortal Confluence
-  policy citations (AI Usage Policy, Privacy, GDPR, Secure Engineering, etc.).
-
-- **`ruby-scripting` skill** deployed — auth patterns, patchVer read-before-write, cross-platform
-  file handling, error handling template for scripts using the ecoportal gem stack.
-
-- **LEARNING markers** seeded in worklog for Phase 0 EPAI pipeline.
-
-- **`.gitattributes`** — LF enforcement.
-
-### No blockers
-
----
-
-## 2026-06-08 — ep-ai-standards v1.0.0 alignment
-
-### Done
-
-- **ep-ai-standards retrofit applied** — `eP_AI_Manager` skill installed at
-  `.ai-assistance/skills/eP_AI_Manager/SKILL.md`. Standards version pinned to v1.0.0
-  in `.ai-assistance/standards-version.json`.
-- **`docs/worklog.md` created** — this file; satisfies `workflows/session-handoff` standard.
-- **CLAUDE.md updated** — "Read these first" section added with worklog pointer; skill index
-  updated to include `eP_AI_Manager`.
-
-### Blocked / Pending
-
-- Active project work (see `.ai-assistance/projects/` for current project state)
-
-### Open Questions
-
-- None at this time.
-
----
-
-## How to use this file
-
-- **Starting a session:** read from the bottom up.
-- **Ending a session:** add a dated section at the top with Done / Blocked / Open Questions.
-- **Per-project detail:** see `.ai-assistance/projects/<slug>/` (INTENT.md, TODO.md, DECISIONS.md).