ecoportal-api-graphql 1.3.5 → 1.3.9

data/docs/worklog.md

@@ -0,0 +1,574 @@
+# 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.
+
+---
+
+## ▶ 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).