ecoportal-api-graphql 1.3.10 → 1.3.12

data/.ai-assistance/code/template_diff_pairing_domain.md

@@ -0,0 +1,175 @@
+# Template Lifecycle, Diffing, Pairing & Deployment — Domain Knowledge
+
+**Status:** authoritative domain capture (harvestable by ep-ai-standards). Sourced from Oscar
+(platform maintainer) 2026-07-03, with schema/code facts verified inline. This is the single
+reference for the template diff/deploy/sync problem space — do not re-derive it from scratch.
+
+Related: `graphql_domain_knowledge.md` (§ genome), `.ai-assistance/projects/template-diff-deploy/`,
+`.ai-assistance/projects/template-maintenance/`, `.ai-assistance/projects/qa-services-delivery/`.
+
+---
+
+## 1. Why this matters
+
+Most quality work in Services Delivery revolves around **template changes** and the **tech-script
+fixes** applied to a register's pages after a **failed QA on a published template** produced wrong
+pages. Templates are the epicenter of admin + troubleshooting automation — **not a QA-only concern**.
+
+## 2. The UAT→PROD template lifecycle and its failure modes
+
+Jira tickets (service **xor** support) raise actions to **change templates** (most commonly). Those
+changes are either:
+- applied **directly to the PROD template** (or a DEV template that becomes PROD on the org launch date), or
+- applied first to the **UAT** site template, then replicated to PROD after customer approval.
+
+Because the whole process is **manual**, it regresses in two directions:
+- **Regression A (lost changes):** someone unpublishes/replaces the PROD template with a **YAML backup
+  copy of UAT**. Any PROD-only changes not present in UAT are **silently lost**.
+- **Regression B (premature release):** UAT already carried changes **not yet approved for release**;
+  replacing PROD with UAT **releases them**, and the customer becomes unhappy.
+
+Current mitigation (costly): hand-account **every** UAT change in detail; the **same staff member**
+who changed UAT re-does those changes in PROD. This introduces its own errors — PROD may differ from
+UAT, or the person forgets some changes. Goal: make this **smooth, effective, efficient** — no extra
+comms, no back-and-forth, no trust loss, no rectifying tech-scripts.
+
+## 3. The core obstacle — no stable identity (MongoDB)
+
+MongoDB assigns a **distinct ID to every object in the nested page hierarchy**, and IDs are **not
+shared** across: template vs its child pages, page vs page, UAT template vs PROD template. Nothing
+has the same ID as its counterpart anywhere.
+
+Consequences seen platform-wide:
+- Customer integrations must **fetch the page model first** just to learn sub-object IDs (e.g.
+  `dataField` ids) before building a patch payload.
+- The **field ref** (a truncated sha of the label name) is used as a pseudo-key in analytics — it's
+  unstable; the **Field ID project** exists to add certainty here.
+
+## 4. THE key distinction — self-version diff vs cross-object diff
+
+| | IDs | Pairing needed? | Difficulty |
+|---|---|---|---|
+| **Self-version** (same object, vN vs vN+1) | **retained** | none — match by id | trivial ✅ **built** |
+| **Cross-object** (UAT↔PROD, page↔template) | **different** | yes — equivalence | hard |
+
+- **Self-version** captures "what did this ticket change to the UAT template" exactly, as long as the
+  original snapshot was retained. Implemented: `Ecoportal::API::GraphQL::Diff::VersionDiff` (gem).
+- **Cross-object** is the hard one: to diff, you must **pair counterpart objects** across two id-spaces,
+  translate to a common id-space in memory, diff, then map back. Only a fully-mapped copy can be diffed.
+
+## 5. The genome signature — VERIFIED facts + why it can't be the sole key
+
+**What it is:** an identifier introduced by the original ecoPortal developer (~2015/16) intended to
+pair objects across a template and its child pages, and across YAML backup→restore. The genome is
+**inherited** template-(sub)object → child-page-(sub)object, and copied on restore. It **grows** each
+time it is restored or a child page is created (a related backend commit had to be amended for this).
+
+**⚠️ VERIFIED 2026-07-03 (corrects the older "not exposed" claim in `graphql_domain_knowledge.md`):**
+The live NewEp GraphQL schema (`.ai-assistance/tmp/20260605T101224_live_ep_graphql_schema.graphql.json`)
+**DOES expose `genomeSignature: String`** on the **`DataFieldsInterface`** and on **every concrete
+data-field type** (PlainText, RichText, Date, Number, Gauge, People, Select, Checklist, TagField, Geo,
+Signature, ContractorEntities, CrossReference, ImageGallery, File, Mailbox, ActionsList, Law,
+AiSummary, TableField, Chart, FrequencyRateChart, EmbeddedStructure, PageAction). APIv2 also exposed it
+(developer "Rien" eventually exposed everything). It is **on data fields, not on sections/stages/pages**
+(per the introspection). **Our gem does NOT yet request it** — no fragment/model field — so to use it
+we add `genomeSignature` to the data-field fragment + `Base::Page::DataField`. It is **not indexed** in
+Elasticsearch.
+
+**Why genome is NOT an unarguable pairing key (Oscar's failure modes — design constraints):**
+- (a) pairing was **manual**, with no platform support;
+- (b) **new features** (new field types, linked-field configs, …) were never added to the genome solution;
+- (c) it's **wrong for select options** — an option's key is the **value (primary)** or **name
+  (auxiliary)**, never the genome;
+- (d) it wrongly **syncs checklist fields** from the template (shouldn't happen);
+- (e) the premise "genome is always an unarguable pairing key" is **false**: a configurator may
+  **re-use** a field for something else then add a same-name/type field (realising the mistake); a
+  structural/conceptual **revamp** may carry same-label/type fields re-used for a different purpose; or
+  a field is **re-purposed** keeping its genome (e.g. `Date logged:` → `Date of sign-off:`);
+- (f) **data-loss accounting** is incomplete and under-documented.
+
+The abandoned backend solution built on genome: `app/services/migration/*`, notably
+`Migration::GenomeKindship` — synced children pages to their parent template via genome pairing.
+Abandoned for the reasons above, but its **founding principle is valid** (see §6).
+
+## 6. The load-bearing simplifying principle (valid)
+
+**Sections/stages are scaffolding, NOT data containers.** Customer data lives in the **data-fields**
+(+ core page properties: old tags → now `location_ids` + `custom_tags`, `created_at`, …). Therefore
+**restructuring is tractable as long as you can pair the customer data between the original-stage
+field and the end-state field.** This dramatically shrinks the problem: **pair fields precisely; treat
+structure as context.** That `genomeSignature` lives on data-fields aligns exactly with this.
+
+Proven in practice by the migration-scripts framework (`doc/scripts/v*`): field-pairing via `FIELDS_MAP`
+(`20231129_stolt_tra_migrate.rb`, `20240125_gns_con_migrate.rb`); later, due to page variability in
+some registers, a different approach — **re-import via the current template's import spreadsheet**
+(customer fills a data CSV extract) + a final tech-script for non-importable fields
+(`20251202_luna_park_migration.rb`, `20260615_resene_copy_files.rb`).
+
+## 7. Pairing = equivalence matching (the reframe — CONFIRMED by Oscar 2026-07-03)
+
+Stable identity across independent Mongo objects does not exist, so **reframe from identity to
+EQUIVALENCE** — a **record-linkage / entity-resolution** problem:
+
+- Combine **multiple weak signals** into a **confidence score**:
+  `genomeSignature` (strong, now available on data fields), **type + label** (already implemented:
+  eco-helpers `HelpersMigration::TypedFieldsPairing` / `copying.rb`), **section heading + position**,
+  **select options-by-value**, structural context.
+- **Auto-accept** high confidence; **route ambiguous / low-confidence to a HUMAN**; the assistant asks
+  the user to resolve unmatched cases and adjudicate doubtful pairings.
+- **Persist every decision to a LEARNING LEDGER** (confirmed a first-class artifact): the pairings +
+  the log of *how* each was resolved, for future reuse. Over time most cases auto-resolve; the tool
+  asks only about genuine novelty. The accumulated ledger also **feeds Product's Field-ID /
+  template-entity-id** effort (we are the interim bridge that generates their data).
+
+## 8. Diff MODALITIES — multiple diff forms for different processes (Oscar 2026-07-03)
+
+There is **no single diff**. Different processes need different modes. Fields may **move between
+sections**, or **must go to a specific section** — some processes care about section membership,
+others only about the field's data pairing. The engine is a **family of strategies** over configurable
+axes:
+
+- **Pairing strategy:** by-id (self-version) · genome · type+label · assisted/ledger (cross-object).
+- **Comparison scope:** structural (stages/sections/fields) · config-only (field configuration,
+  options, forces) · data-migration (field→field data pairing, structure-agnostic).
+- **Move sensitivity:** section-move-aware vs section-agnostic; ordering-sensitive vs -insensitive.
+- **Direction/intent:** changelog (what changed, for a ticket) · deployment delta (UAT→PROD replay) ·
+  sync-readiness (can this register/subset be synced to the active template?).
+
+`Diff::VersionDiff` implements the **self-version, id-paired, structural, section-move-aware** mode.
+The others compose the same `Change` output with a different pairing front-end and comparison scope.
+
+## 9. Layering — where each capability lives (CONFIRMED)
+
+| Layer | Owns | Consumers |
+|---|---|---|
+| **ecoportal-api-graphql** (gem) | *mechanics*: read model, WorkflowCommand vocab, build (emitter) + **diff (VersionDiff)** + apply; `genomeSignature` fragment (to add) | everyone |
+| **eco-helpers** | *orchestration*: pairing engine (human-in-loop), learning ledger, samples, session flows, `TypedFieldsPairing` | tools, scripts |
+| **ecoportal-qa** | QA-facing surface (checks/reporters/Jira/CLI); **should use the gem's model, not re-implement it** | QA team |
+| admin / troubleshooting / integrations | consume gem + eco-helpers directly | — |
+
+## 10. The pipeline (how the pieces compose)
+
+```
+pair (id | genome | type+label | assisted+ledger)
+     └─► diff on paired model (mode-specific)
+             └─► delta as WorkflowCommands (the emitter)
+                     └─► apply to target ─► verify (ecoportal-qa) ─► monitor (register sync-ready tickboxes)
+```
+The **self-version changelog** is a portable "commit": a `Change` set that, once id-translated through
+a pairing map, **replays onto PROD**.
+
+## 11. Product context
+
+Register-template-sync is **not yet scoped** by Product (Field-ID takes precedence). Product is working
+out a **template-entity-id** to differentiate template versions within a register (to pair pages made
+from a previous template version with the current one) + **customer filters by template**. Our tools
+are the interim bridge and **generate the pairing data** Product needs.
+
+## 12. Status & next steps
+
+- ✅ **Done:** `Diff::VersionDiff` (self-version, exact, id-paired) — gem, 8 specs.
+- **Next:** (1) add `genomeSignature` to the data-field fragment + `Base::Page::DataField`; (2) synthesise
+  WorkflowCommands from a `Change` set (delta → commands); (3) the **pairing engine** (equivalence,
+  multi-signal, human-assisted, ledger) in eco-helpers; (4) **diff modalities** as strategies;
+  (5) cross-template deploy (UAT→PROD replay); (6) monitoring / sync-readiness; (7) tighten `ecoportal-qa`
+  to use the gem's page-model instead of its own `TemplateModel`.

data/.ai-assistance/code/workflow-command-guide.md

@@ -436,3 +436,31 @@ payload = Mutation::Page::ExecuteWorkflowCommands.new(client).query(
 raise "Commands failed: #{payload.body.inspect}" unless payload.success?
 puts "Applied #{cmds.size} commands. New patchVer: #{payload.patchVer}"
 ```
+
+---
+
+## Schema realities — input-key gotchas (verified 2026-07-04 against the live introspection dump)
+
+These are the ways the command bus does **not** behave the way you'd expect. Verifying against the
+schema dump (`.ai-assistance/tmp/*_live_ep_graphql_schema.graphql.json`) before assuming a key exists
+saves a live round trip.
+
+- **`addField` (`WorkflowAddFieldInput`) keys = EXACTLY** `placeholderId, fieldType, label, stageId`
+  (NON_NULL), `sectionId` (NON_NULL), `column`. It does **not** accept `description` or `required`.
+- **A field's `description` is set via `editFieldConfiguration`** (`WorkflowEditFieldConfigurationInput`
+  has a top-level `description: String`), NOT via `addField`. To build a field *with* a description
+  (e.g. a CSV / hidden-field **identity token**), emit `addField` then a follow-up
+  `editFieldConfiguration(dataFieldId: <field>, description:)`. This is the seam `Diff::CommandSynthesizer`
+  and `Builder::TemplateBuilder` use (via `placeholderId`/`ref` when the field is created in the same batch).
+- **`required` cannot be set through the command bus at all.** There is **no `required` input key
+  anywhere** — not on `WorkflowAddFieldInput`, not on `WorkflowEditFieldConfigurationInput` (top-level),
+  not on any of its **12 `byType` sub-inputs**. Treat field-`required` as **read-only / out-of-band**:
+  read it from the template, don't try to mutate it. (ecoportal-qa `:skip`s `required`-readiness for
+  this reason; `VersionDiff`'s `BYTYPE_CONFIG` omits it.)
+- **Structural back-refs:** an added field's `addField` carries its parent `sectionId` + `stageId`;
+  an added **section** has no stage-id key, so wire it with a follow-up
+  `addStageSection(stageId:, sectionId:)`. `Diff::CommandSynthesizer` threads all of these via
+  `placeholderId`/`ref()` (parent placeholder when same-batch, else real id; omitted when unknown).
+
+**Rule of thumb:** before adding a key to a `WorkflowCommand` builder, confirm it exists on that input
+type in the schema dump. Absent keys are silently dropped (or rejected) — they do not error informatively.

data/.ai-assistance/projects/ooze-graphql-native-migration/INVENTORY.md

@@ -0,0 +1,136 @@
+# INVENTORY — Ooze → Native GraphQL Migration (Phase 0)
+
+Verified 2026-07-02 against actual code in `eco-helpers` (main code), `ecoportal-api-graphql`
+(gem), and `implementation/training` (downstream consumers). This is the **master schedule
+partition**: which cases can migrate now vs. are blocked on forces, and the BC surface that must
+keep working with **zero customer-script edits**.
+
+> **Scope note (Oscar, 2026-07-02):** this project currently builds the **native GraphQL classes
+> only**. We do NOT yet flip the `OozeSamples::*` names to delegate, and we do NOT remove shim
+> code. The delegation flip happens "long after we know everything works on the native samples."
+
+---
+
+## A. The ooze case inheritance tree (eco-helpers)
+
+Root path: `lib/eco/api/usecases/ooze_samples/`
+
+```
+Eco::API::Common::Loaders::UseCase
+├─ OozeSamples::OozeBaseCase                       (ooze_base_case.rb)  include Helpers, Helpers::Rescuable
+│   └─ OozeSamples::OozeRunBaseCase                (ooze_run_base_case.rb)  single-ooze runner
+│       └─ OozeSamples::OozeUpdateCase             (ooze_update_case.rb)
+│           └─ OozeSamples::OozeFromDocCase        (ooze_from_doc_case.rb)  + Word-doc parsing
+│   └─ OozeSamples::RegisterUpdateCase             (register_update_case.rb)  include Helpers::Creatable   ← CUTOVER #1
+│       └─ OozeSamples::TargetOozesUpdateCase      (target_oozes_update_case.rb)  CSV target ids           ← CUTOVER #2
+│       └─ OozeSamples::RegisterMigrationCase      (register_migration_case.rb)  include HelpersMigration
+└─ OozeSamples::RegisterExportCase                 (register_export_case.rb)  standalone (NOT under OozeBaseCase)
+    └─ OozeCases::ExportRegisterCase               (ooze_cases/export_register_case.rb)  include ExportableRegister
+```
+
+### Control-flow loop a native class must reproduce (RegisterUpdateCase)
+
+- `main(session, options, usecase, mode: :legacy)` → init KPIs → `:legacy` runs
+  `with_each_entry { process_ooze(&block) }`; `:delegate` yields for a custom loop → log KPIs.
+- `with_each_entry` → `batched_search_results` yields page batches → per page: dedup check →
+  `ooze(id)` load → yield to block → `update_oozes` (batch save).
+- `batched_search_results` → `apiv2.registers.search(register_id, search_options) { ... }`,
+  batch-size chunking.
+- `search_options` → sort=created_at asc, `conf_search` (→ `search` hook), `conf_filters`
+  (→ `filters` hook).
+- KPI counters: `total_search_oozes`, `retrieved_oozes`, `dupped_search_oozes`, `updated_oozes`,
+  `failed_update_oozes`, `created_oozes`, `ooze_create_attempts`.
+- Dry-run: `results_preview` (confirm total, 10s timeout); `display_patch` / `backup_patch!` in base.
+- Internal batch queue: `enqueue` / `queue_shift` / `queue_get` (duck-types v2 Page / PageStage /
+  anything responding to `dirty?` + `as_update`).
+
+`TargetOozesUpdateCase` overrides only `with_each_entry` (reads target ids from CSV column 1+,
+batches by size) — everything else inherited.
+
+**Native counterpart already has a head start:** eco-helpers
+`lib/eco/api/usecases/graphql/samples/pages/page/base.rb` already implements a **native GraphQL
+loop** (`process` → `init_kpis` → `each_page` → `process_page` → `log_kpis`, plus `update_page`
+with a simulate guard and register-scoped `search_conf`). The native register case builds on this
+`Pages::Page::Base`, NOT on a v2 loop.
+
+---
+
+## B. Helper modules — v2-coupled vs pure
+
+Root: `lib/eco/api/usecases/ooze_samples/helpers/` and `helpers_migration/`
+
+| Module | Path | Classification | Migration action |
+|---|---|---|---|
+| `Helpers::Shortcuts` | helpers/shortcuts.rb | **PURE** (string simplify/compare; one `obj.force` in a message) | Port ~verbatim to `graphql/helpers/pages/` |
+| `Helpers::Filters` | helpers/filters.rb | **PURE** (tag/date filters, time math) | Port ~verbatim |
+| `Helpers::Rescuable` | helpers/rescuable.rb | error-rescue wrapper | Port (thin) |
+| `Helpers::Creatable` | helpers/creatable.rb | **v2-coupled** (`apiv2.pages.get_new/create`; duck-types v2 Page) | GraphQL re-expression (native draft + create) |
+| `Helpers::OozeHandlers` | helpers/ooze_handlers.rb | **v2-coupled** (`merge_values` case-matches `V2::Page::Component::*`) | GraphQL-typed re-expression (per data-field type) |
+| `Helpers::ExportableOoze` | helpers/exportable_ooze.rb | v2-coupled (field value reads) | later (export cases) |
+| `Helpers::ExportableRegister` | helpers/exportable_register.rb | v2-coupled (ooze value aggregation) | later (export cases) |
+| `HelpersMigration::Copying` | helpers_migration/copying.rb | **v2-coupled** (field pairing/copy) | later (migration case) |
+| `HelpersMigration::TypedFieldsPairing` | helpers_migration/typed_fields_pairing.rb | **v2-coupled** (type+label pairing) | later (migration case) |
+
+**First-wave port:** `Shortcuts`, `Filters`, `Rescuable` (pure/thin) + a native `Creatable`.
+
+---
+
+## C. The compat shim being retired (NOT this session)
+
+`lib/eco/api/usecases/graphql/compat/ooze_redirect.rb` (+ `ooze_redirect/{dirty_array,field_patches,force_compat}.rb`).
+
+- `OozeRedirect.included(base)` → `FieldPatches.apply!` (global v2-class reopening + GraphQL field
+  prepends), `base.include(GraphQLEnv)`, `base.prepend(Infrastructure)`,
+  `+ ForceCompat::Infrastructure if force_support?` (currently `false`).
+- `Infrastructure` overrides (the leaf ops a native class implements directly instead):
+  `api_v2`/`apiv2` → `graphql`; `stage(name)` → `StageView`; `with_fields(ooz, type:, label:)` →
+  reads `ooz.components`; `dirty?` → `.dirty?` or captured submit/sign-off flags.
+- `FieldPatches` steps: v2 `===` dispatch lie; GraphQL BasePage `submit!`/`sign_off!` + pending
+  flags; People `DirtyArray`; CrossReference `reference_ids`/`add`/`clear`; Select
+  `options`/`select`/`deselect`/`values`.
+
+A native class needs NONE of these patches — it dispatches on GraphQL types directly.
+
+---
+
+## D. Forces partition (blocked until GraphQL forces endpoint is live)
+
+- **Base ooze cases (A) do NOT use forces** — `OozeBaseCase`, `RegisterUpdateCase`,
+  `TargetOozesUpdateCase`, `RegisterMigrationCase`, `RegisterExportCase` are all force-free.
+  → **All first-wave cutover cases are migratable now.**
+- **Forces live only in downstream training scripts** that subclass the register cases:
+  | Script | Base | Force usage |
+  |---|---|---|
+  | `les_mills_force_update_case.rb` (Test_Les) | RegisterUpdateCase | `forces.get_by_name` → `force.custom_script =` |
+  | `20231031_fix_options_case.rb` (FIXOPTIONS) | RegisterUpdateCase | `forces.each` → `force.custom_script =` |
+  | `08102024_THL_RemoveLocTitle_case.rb` (REMOVELOCTITLEHAZ) | RegisterUpdateCase | `forces.get_by_name` → `custom_script =` |
+  | `rename_field_case.rb` (AddFieldBinding) | RegisterUpdateCase | `forces.delete!` |
+  | `attach_image_case.rb` (AttachImage) | TargetOozesUpdateCase | `forces.get_by_name` |
+- **Note:** the gem *does* ship forces write commands via the command bus
+  (`addForce`/`editForce`/`addBinding`/…) and `OozeRedirect.force_support?` being `false` is
+  stale/conservative (see memory `forces-via-workflow-commands`). But the ooze-case force *read*
+  path (`target.forces.get_by_name`, `force.custom_script=`) is a different surface and its
+  GraphQL end-to-end readiness is UNCONFIRMED. These scripts stay on the v2 path until confirmed.
+
+---
+
+## E. Downstream include-site inventory (BC surface)
+
+- Training repo `C:\ruby_scripts\implementation\training` **exists**; **273+ custom cases**.
+- **All are still APIv2-only** — none currently `include GraphQL::Compat::OozeRedirect` (the live
+  TOOCS/CANS cutover scripts that DO use it are not in this training tree — locate them before any
+  flip; not needed this session since we are not flipping).
+- Overrides seen across consumers (the hooks a native class must keep honoring):
+  `process_ooze` (always), `search`, `filters`, `custom_processing`, plus script-local helpers
+  (`with_target_stage`, `target_stage`, `with_target_field`, `with_target_force`, etc.).
+
+---
+
+## F. Migration order (schedule)
+
+1. **Now (native only):** port pure helpers (`Shortcuts`, `Filters`, `Rescuable`) + native
+   `Creatable`; native register base case on top of `Pages::Page::Base`; specs. **No flip.**
+2. Native `RegisterUpdateCase` + `TargetOozesUpdateCase` counterparts; A/B parity harness.
+3. (Later) flip old names → delegate, per-case, parity-gated; remove shim slices.
+4. (Blocked) force-using cases — pending GraphQL force read/write end-to-end confirmation.
+5. (Later) export + migration cases (`ExportableRegister`, `Copying`, `TypedFieldsPairing`).

data/.ai-assistance/projects/ooze-graphql-native-migration/TODO.md

@@ -5,9 +5,14 @@ Legend: `[ ]` todo · `[~]` in progress · `[x]` done · `[!]` blocked (see Risk
 Each phase ends with a gate. **Do not flip an old class name to delegate until that
 case's parity result is recorded in DECISIONS.md.**
 
+> **STATUS 2026-07-02:** Phase 0 inventory DONE → see `INVENTORY.md`. Scope narrowed by Oscar:
+> **build the native GraphQL classes ONLY this cycle** — no delegation flip, no shim removal yet
+> (those come "long after we know everything works on the native samples"). So Phases 1–2 (native
+> classes + specs) are IN; the flip/removal steps stay `[ ]` until Oscar green-lights.
+
 ---
 
-## Phase 0 — Inventory & Baseline (no code changes)
+## Phase 0 — Inventory & Baseline (no code changes)  ✅ DONE 2026-07-02 (see INVENTORY.md)
 
 ### 0a. Map the full ooze case inheritance/include tree
 - [ ] Confirm the inheritance chain (verified 2026-06-30, re-confirm before building):

data/.ai-assistance/projects/qa-services-delivery/DECISIONS.md

@@ -0,0 +1,93 @@
+# Decisions — QA-as-CI/CD (ecoportal-qa)
+
+Append per decision; never delete — history matters.
+
+---
+
+## [2026-07-02] Standalone repo, governed by ep-ai-standards (not built inside it)
+
+**Context:** Oscar was unsure whether ep-ai-standards tooling should live in its own repo or inside
+ep-ai-standards, noting it "shouldn't matter as long as results don't clash and ep-ai-standards can
+pick it up and ensure continuity."
+
+**Decision:** **Standards & governance live in ep-ai-standards; implementations live where their
+dependencies live.** `ecoportal-qa` depends on the GraphQL gem → its own repo. It carries a
+`.ai-assistance/` **conformance declaration** (`conformance.json` + `CLAUDE.md`) so ep-ai-standards
+can discover, index, and govern it without owning the code.
+
+**Reason:** Makes "location doesn't matter" true *by construction*: continuity via the declaration,
+no clash via shared conventions. Keeps the governance repo lean and each tool independently testable.
+
+---
+
+## [2026-07-02] A QA "pseudo-language" (declarative DSL) → compiler → jobs
+
+**Decision:** QA authors declarative **check-sets** in a small YAML DSL (front-end). A Ruby
+**compiler** turns them into runnable Check objects (IR), and later into CI-job / auto-approve
+backends.
+
+**Reason:** Delegation surface for QA (no Ruby needed); front-end/back-end split insulates QA
+templates from the volatile WorkflowCommand/GraphQL API. Proven pattern (Great Expectations,
+Gherkin, policy-as-code, CI-as-code).
+
+**Consequences:** The DSL schema is a public contract to keep stable; compiler backends can churn.
+
+---
+
+## [2026-07-02] Read-only, canonical-JSON result, honest skips
+
+**Decision:** The runner is **read-only** end to end. Every run emits one **canonical Result JSON**
+(ticket · target · verdict · per-check outcome) that all reporting derives from and that is the audit
+record. Checks that can't be evaluated (e.g. a `required` flag not captured in a snapshot) return
+**`:skip`**, never a false pass; verdict distinguishes `passed` / `passed_with_gaps` / `changes_requested`.
+
+**Reason:** Safety/privacy (no writes), governance (auditability), and trustworthy results (a skip is
+not a pass) are the stated decision drivers.
+
+---
+
+## [2026-07-02] Jira phased; human-in-the-loop; auto-approve last & opt-in
+
+**Decision:** Phase Jira integration: **read + post results + human-gated transition first**; the
+**auto-approve hook is built last, opt-in, and QA-owned** (off by default). Jira is the
+ticket-management workflow layer, not the check engine.
+
+**Reason:** Services & Delivery is a human team; agents assist, not replace. Governance/human gate are
+non-negotiable. Lowest-risk capability (read-only + report) delivers value before any transition logic.
+
+---
+
+## [2026-07-02] Ruby core, no runtime deps in the core
+
+**Decision:** Core (DSL/compiler/runner/reporters) has **no runtime gem dependencies** — it operates
+on a page/template doc Hash. `Source::GraphqlSource` lazily requires `ecoportal-api-graphql` only when
+run against a live org.
+
+**Reason:** Ruby for team resourcing redundancy; a dependency-free core stays offline-runnable and
+trivially testable (specs run against a captured snapshot), and keeps CI fast.
+
+---
+
+## [2026-07-03] PROPOSED — Jira adapter: interface + REST first, MCP later (pending Oscar)
+
+**Context:** Phase 3 posts results to Jira. Two ways in: the Atlassian MCP (no secrets, but may be
+absent in headless/CI runs) vs Jira REST (needs a managed service-account token, but works everywhere).
+
+**Proposed decision:** define a `Jira::Client` interface and implement **`RestClient` first**; add
+`McpClient` later as an interactive convenience. The endgame is Phase 4 CI ("ticket as pipeline"),
+where MCP likely isn't available — REST is the durable path and won't need redoing. The interface
+makes it a drop-in choice, not a fork. **Not yet ratified** — awaiting Oscar's answers on the target
+Jira project, workflow statuses, and whether a service-account token is available (see PHASE3-SCOPE.md).
+
+**Reason:** avoid building a channel that can't run where the destination (CI) lives.
+
+---
+
+## [2026-07-03] Phase 3 does NOT auto-transition (reaffirms human-in-the-loop)
+
+**Decision:** the Jira adapter's default is **report-only** (post a redacted, idempotent result
+comment); a status transition happens **only** when a human explicitly names one (`--transition`).
+Auto-approve stays out of scope until Phase 5 (opt-in + governed + audited).
+
+**Reason:** the human gate is non-negotiable; posting a result is useful on its own and carries no
+risk, so it ships first while transition automation waits for the governed Phase 5 design.

data/.ai-assistance/projects/qa-services-delivery/INTENT.md

@@ -0,0 +1,76 @@
+# Project: QA-as-CI/CD for Services Delivery (ecoportal-qa)
+
+**Created:** 2026-07-02
+**Status:** active — Phase 1 prototype built
+**Primary repo:** `ecoportal-qa` (`C:\ruby_scripts\git\ecoportal-qa`) — NEW standalone Ruby tool
+**Reads via:** `ecoportal-api-graphql` (the GraphQL client gem)
+**Governed by:** `ep-ai-standards` (conformance declared in `ecoportal-qa/.ai-assistance/`)
+
+> **Why the plan lives here:** `ecoportal-qa` is the implementation repo; the team's project-cycle
+> docs live in `ecoportal-api-graphql/.ai-assistance/projects/` (same pattern as the ooze migration).
+
+---
+
+## Problem
+
+The QA team in **Services Delivery** reviews **org configuration & template changes** against Jira
+tickets before sign-off. Today this is manual and slow. They want to (a) quickly see *what has been
+done*, (b) author repeatable **automated checks** that save review time, and (c) eventually gate
+Jira ticket transitions on those checks — with **humans always in the loop** (this is a Services &
+Delivery team; agents/AI assist, they don't replace people).
+
+## Vision — "QA-as-CI/CD"
+
+QA authors checks once, in a friendly declarative language; a Ruby compiler turns them into runnable
+jobs; results flow to reporting + Jira; humans gate the transitions.
+
+```
+QA template (YAML DSL)  →  Compiler (Ruby)  →  runnable Checks  →  Runner (read-only)  →  Result (JSON)
+     ▲ what QA writes         ▲ front-end→IR                          ▲ vs live/captured template   ▲ reporting · Jira · monitoring
+```
+
+Classic compiler split: QA owns a **stable front-end language**; the compiler emits **volatile
+back-end job code**. That insulation matters — the underlying WorkflowCommand/GraphQL API is volatile,
+and QA templates must not break when it shifts.
+
+## Decision drivers (Oscar)
+
+safety · privacy · simplicity · **delegation to the QA team** · monitoring · reporting · governance ·
+Ruby (resourcing redundancy) · human-in-the-loop. Jira is *where the ticket-management workflow is
+handled*, not where the engine runs.
+
+## Scope
+
+### In scope
+- The **QA DSL** (declarative check-set: `meta.ticket/target` + `expect.stages→sections→fields`).
+- A **compiler** (DSL → ordered, stateless Check objects / IR).
+- A **runner** that verifies checks **read-only** against a live or captured template.
+- A **canonical Result** (JSON) — the single source of truth for all reporting + the audit record.
+- Sources: `FixtureSource` (offline JSON snapshot) + `GraphqlSource` (live, read-only, via the gem).
+- Reporters: JSON (canonical) + Text now; CSV/HTML next.
+- **ep-ai-standards conformance** stub so the tool is discoverable/governed without being owned.
+
+### Out of scope (non-goals / later)
+- **Writing** to orgs from the check path (read-only by design — safety/privacy).
+- **Auto-approval** without a human — only ever an opt-in, QA-owned hook, built last.
+- Building QA templates for every customer (that's QA's ongoing authoring, enabled by this tool).
+- Replacing human QA judgement.
+
+## Subject of review (confirmed)
+**Org config & template changes** — templates/registers/workflows/fields/forces — sourced from the
+GraphQL API. (A template IS a page, so structure reads via the page model.)
+
+## Precedents (this pattern is proven)
+- **Great Expectations** — declarative "expectations" → validation engine → results + data docs
+  (closest 1:1 analogy; "config/template expectations").
+- **Gherkin/Cucumber** — a QA-writable language compiled to executable steps.
+- **OPA / policy-as-code** — declarative rules → decisions + audit (governance model).
+- **GitLab/GitHub CI-as-code** — YAML pipelines → jobs (the "ticket as pipeline" backend target).
+
+## Success criteria
+1. QA can author a check-set in YAML and get a green/red result against a real template with **zero
+   Ruby**. *(Phase 1 — DONE against the toocs snapshot.)*
+2. Results are canonical JSON, auditable (ticket · target · verdict · per-check), and human-readable.
+3. Read-only end to end; no PII leaks in results/logs.
+4. Jira transitions are human-gated; auto-approve is opt-in and off by default.
+5. The tool is discoverable/governed by ep-ai-standards via its conformance declaration.

data/.ai-assistance/projects/qa-services-delivery/PHASE3-SCOPE.md

@@ -0,0 +1,115 @@
+# Phase 3 — Jira adapter (human-gated) — SCOPE
+
+**Status:** SCOPED (not built) — 2026-07-03. Building is blocked on two Oscar decisions (below).
+**Repo:** `ecoportal-qa`. **Depends on:** Phase 1–2 (Runner + canonical Result + Reporters + Redactor).
+
+---
+
+## Goal
+
+Connect the QA runner to **Jira** so a QA run is: (1) **traceable** to a ticket, (2) its result is
+**posted back** to that ticket, and (3) a **human gates** any status change. Phase 3 does **not**
+auto-transition — that is Phase 5, opt-in and governed. Jira is the *ticket-management workflow layer*;
+the check engine stays exactly as built.
+
+Non-goal (Phase 3): automatic transitions, running on a Jira webhook (that's Phase 4 CI), editing
+ticket content beyond a result comment + an optional verdict field.
+
+---
+
+## The one idea that keeps this simple
+
+Everything already funnels into **one canonical `Result`** (ticket · target · verdict · per-check).
+The Jira adapter is **just another consumer of that Result** — exactly like the CSV/HTML reporters.
+It never reaches into the runner or the checks. So Phase 3 adds a *channel*, not a *rewrite*.
+
+```
+Runner ─► Result ─┬─► Reporters (text/json/csv/html)   [Phase 1–2]
+                  └─► Jira::Publisher ─► Jira::Client ─► a ticket   [Phase 3]  ← new channel only
+```
+
+---
+
+## Design
+
+### Traceability (ticket ↔ check-set)
+- The link is the check-set's `meta.ticket` (e.g. `SD-1234`). **Push model:** you run a check-set,
+  the adapter posts to the ticket named in its `meta`.
+- A reverse index (ticket → check-set file) is derivable by scanning `qa/checks/` — deferred until we
+  know where check-sets live long-term (Open Q #4).
+
+### Components (all new, in `ecoportal-qa`)
+- **`Jira::Client`** — a thin interface: `find_issue(key)`, `add_comment(key, body)`,
+  `set_field(key, field, value)`, `available_transitions(key)`, `transition(key, name)`.
+- **`Jira::RestClient`** — real implementation over Jira Cloud REST v3 (base URL + service-account
+  API token from ENV/secret store). *Recommended first implementation* (see decision below).
+- **`Jira::McpClient`** — optional implementation over the Atlassian MCP (no secrets in our code).
+- **`Jira::DryRunClient`** — records intended calls, performs none. The offline test double + the safe
+  default for `--dry-run`. (Same pattern as `Source::FixtureSource`.)
+- **`Jira::Publisher`** — orchestrates: render the result (TextReporter for the comment, JSON/HTML as
+  attachment), **redact first** (Redactor), post the comment, optionally set a verdict field, and —
+  only when a human explicitly asks — offer/perform a transition.
+
+### Human-in-the-loop transition model (the safety crux)
+Phase 3 supports three modes, defaulting to the safest:
+1. **`--dry-run`** (default in CI-less/interactive) — print what *would* be posted; touch nothing.
+2. **report-only** — post the result comment (+ optional verdict field); **leave the transition to
+   the human in the Jira UI.** This is the recommended day-one mode.
+3. **`--transition "<name>"`** — a person runs this explicitly after reading the result; the tool
+   performs that one named transition. The tool NEVER picks/performs a transition on its own.
+
+### Governance / safety
+- **Redact before posting** (comments can be widely visible) — reuse the Phase-2 Redactor.
+- **Secrets**: REST token from ENV/secret store, scoped to comment + transition on the target project
+  only; never committed. MCP path carries no secrets in our code.
+- **Idempotency**: tag the comment with a hidden marker (`<!-- ecoportal-qa:run SD-1234 -->`) so a
+  re-run *updates* its previous comment instead of spamming the ticket.
+- **Audit**: every Jira call appended to a run log (issue · action · verdict · timestamp · actor).
+- **Least action**: the default does not transition; transitions are explicit, named, human-invoked.
+
+### CLI surface (extends Phase 2)
+```
+ecoportal-qa report CHECKSET.qa.yml --source fixture:PATH|graphql:ID \
+    --jira [--jira-client rest|mcp|dry-run] [--transition "QA Approved"] [--redact] [--attach json,html]
+```
+- No `--jira` → behaves exactly like Phase 2 `run` (prints a report).
+- `--jira` without `--transition` → report-only (comment + optional field).
+- Exit code still encodes the verdict (CI-friendly).
+
+---
+
+## Decision needed: Atlassian MCP vs Jira REST
+
+| | Atlassian MCP | Jira REST API |
+|---|---|---|
+| Secrets in our code | none (session auth) | service-account token (managed) |
+| Works in CI / headless | **uncertain** — interactive-auth MCP servers may be absent in headless/cron | **yes** |
+| Setup speed (interactive) | fast | moderate |
+| Control / stability | good, but tied to MCP availability | full, documented |
+
+**Recommendation:** build the **`Jira::Client` interface + `RestClient` first**. Reason: the endgame
+is Phase 4 CI ("ticket as pipeline"), where MCP likely isn't available; REST works everywhere, so it's
+the durable path and doesn't have to be redone. Add `McpClient` later as an interactive convenience.
+The interface makes this a drop-in choice, not a fork.
+
+---
+
+## Sub-phases (build order once unblocked)
+- **3a** — `Jira::Client` interface + `Jira::DryRunClient` + `Jira::Publisher` (format/redact/idempotency).
+  **Fully offline-specable** (DryRunClient records calls) — same as Phase 1–2, no live Jira needed.
+- **3b** — `Jira::RestClient` (config: base URL, token, project) + integration behind an env-gated spec.
+- **3c** — CLI `report --jira …` wiring + audit log.
+- **3d** — (optional) `Jira::McpClient`.
+
+**Gate 3:** a QA run posts a redacted, idempotent result comment to a real ticket; transitions only
+happen when a human names one. No auto-transition anywhere.
+
+---
+
+## Open questions (Oscar) — these block the build
+1. **Which Jira project + workflow statuses?** Need the exact transition names QA uses
+   (e.g. `In QA → QA Approved` / `Changes Requested`).
+2. **REST service-account + API token**, or start **MCP-only interactive**? (Drives 3b vs 3d order.)
+3. **Verdict field**: a dedicated custom field, or comment-only for now?
+4. **Where do check-sets live** long-term (repo `qa/checks/`, per-customer, shared config repo)? —
+   affects the reverse ticket→check-set index (deferred until answered).