ecoportal-api-graphql 1.3.9 → 1.3.11

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).

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

@@ -0,0 +1,99 @@
+# ROADMAP — where ecoportal-qa is going, and how the pieces get us there
+
+A narrative companion to INTENT/DECISIONS/TODO. Read this when you want the *why* and the *shape of
+the journey*, not the task list.
+
+---
+
+## The destination (the "north star")
+
+> QA in Services Delivery verifies org config & template changes **faster, consistently, and
+> auditably** — and over time those checks run **as a human-gated pipeline on the Jira ticket**, so
+> QA spends their attention on *judgement* (does this design meet the customer's intent?) instead of
+> *mechanical checking* (is field X present, of type Y, in section Z?).
+
+Two things stay true at every step: **the tool is read-only against orgs**, and **humans make the
+decisions**. Agents/automation assist; they never approve on their own.
+
+---
+
+## Why this shape — one Result, many channels
+
+The whole design rests on a single idea: **every run produces one canonical `Result`** (ticket ·
+target · verdict · per-check outcome). Everything else is a *consumer* of that Result.
+
+```
+        what QA means            turns intent          verifies,            the single
+        (declarative)            into checks           read-only            source of truth
+   ┌───────────────────┐   ┌──────────────┐   ┌───────────────┐   ┌────────────────────┐
+   │  QA template DSL  │ ► │   Compiler   │ ► │    Runner     │ ► │       RESULT       │
+   │  (.qa.yml)        │   │ (front→IR)   │   │ (live/fixture)│   │  (canonical JSON)  │
+   └───────────────────┘   └──────────────┘   └───────────────┘   └─────────┬──────────┘
+                                                                             │
+                    ┌────────────────────────┬───────────────────┬──────────┴───────────┐
+                    ▼                         ▼                   ▼                      ▼
+              Reporters                    Jira                  CI                 Monitoring
+         (text/json/csv/html)         (comment + gate)     (ticket-as-pipeline)   (dashboards)
+              [P1–P2 ✅]                    [P3 ▶]              [P4]                  [P4]
+```
+
+**Why this matters for "how we keep going":** adding Jira (P3), CI (P4), or auto-approve (P5) never
+touches the DSL, compiler, or runner. Each new capability is *another consumer of the Result*. That's
+what lets us extend without rework — and why the QA-facing language (the `.qa.yml`) can stay stable
+even as the WorkflowCommand/GraphQL API underneath churns.
+
+---
+
+## The capability ladder — each rung is independently useful
+
+Each phase delivers value **on its own**, even if we stopped there. That's deliberate: we're never
+"halfway to something that works" — we're "fully at rung N, climbing to N+1."
+
+| Rung | Capability | Value delivered on its own | Status |
+|---|---|---|---|
+| **P1** | **Author & run checks** | QA writes YAML, gets green/red on a real template — repeatable, no Ruby | ✅ done |
+| **P2** | **Report & operate** | CSV/HTML/JSON reports, a CLI, PII redaction, rich checks, CI-ready exit codes | ✅ done |
+| **P3** | **Connect to Jira** | Results land on the ticket QA already works in; human gates transitions | ▶ scoped |
+| **P4** | **Automate the pipeline** | "Ticket as CI pipeline" — checks run on ticket state, results archived, monitored | planned |
+| **P5** | **Delegate the routine** | Opt-in, governed auto-approve when checks pass — humans touch only exceptions | planned |
+
+**Where we are:** top of **P2**. Right now, today, a QA person can author a `.qa.yml`, run
+`ecoportal-qa`, and read a green/red report of a real template. That is already the core value; P3+
+is about *meeting QA where they work* and *removing manual steps*, not about making it "finally work".
+
+---
+
+## How each rung changes the human's day
+
+- **P1–P2 (now):** QA runs a command, reads a report. Faster than eyeballing a template by hand, and
+  the same checks run identically every time.
+- **P3 (next):** QA doesn't leave Jira. The result appears on the ticket; they read it and click the
+  transition themselves. Traceability (which checks, which verdict) is on the ticket forever.
+- **P4:** The run happens *for* them when the ticket moves — no manual step. Same result, same human
+  gate, just no "remember to run it".
+- **P5:** For the routine, all-green cases a team opts into, the ticket can advance automatically —
+  freeing the human to spend time only where a check failed or judgement is genuinely needed.
+
+The trajectory is **less toil, same authority**: at every rung the human still decides; we just remove
+the mechanical work leading up to the decision.
+
+---
+
+## Guardrails that never move (so "going faster" never means "going riskier")
+
+1. **Read-only against orgs** — the check path never writes to a customer org.
+2. **Humans decide** — no auto-transition until P5, and even then opt-in + governed + audited.
+3. **Auditable** — the canonical Result is the record; Jira comments are idempotent and redacted.
+4. **Governed by ep-ai-standards** — the tool declares conformance; standards live there, code lives here.
+5. **QA owns the language** — the `.qa.yml` DSL is the delegation surface; the team writes their own checks.
+
+---
+
+## What could change the plan (honest unknowns)
+- **Sandbox access** — P2's live capture of a real template (`6a3fa5b8…622b`) and P3's live Jira posting
+  both need credentials we don't have yet. Until then we build against fixtures + dry-run clients.
+- **Jira specifics** — project, workflow statuses, MCP-vs-REST (see PHASE3-SCOPE.md). These shape P3/P4
+  but not the core.
+- **Where check-sets live** — repo vs per-customer vs shared config; affects the ticket→check-set index.
+
+None of these block the *core* — they only decide *which channel we wire next and how*.

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

@@ -0,0 +1,81 @@
+# TODOs — QA-as-CI/CD (ecoportal-qa)
+
+Legend: `[ ]` todo · `[~]` in progress · `[x]` done · `[!]` blocked
+
+Code lives in `ecoportal-qa`; this file tracks the plan.
+
+---
+
+## Phase 1 — DSL + compiler + runner + canonical result  ✅ DONE 2026-07-02
+
+- [x] `DSL::CheckSet` — parse + validate a declarative `.qa.yml` (meta.ticket/target + expect tree).
+- [x] `Compiler` — DSL → stateless `Check` objects (stage/section/field exists, field type/options/required).
+- [x] `TemplateModel` — normalised read-only view over a page/template doc (stages→sections→fields).
+- [x] `Source::FixtureSource` (offline JSON) + `Source::GraphqlSource` (lazy live read, read-only).
+- [x] `Runner` + canonical `Result` (verdict passed / passed_with_gaps / changes_requested) with honest `:skip`.
+- [x] `Reporters::{Json,Text}`.
+- [x] Proven end-to-end against the real `toocs_coding_page.json` snapshot (7 pass / 2 fail / 3 skip).
+- [x] 11 specs green; rubocop clean (team `.rubocop.yml`); ep-ai-standards conformance stub.
+
+**Gate 1:** QA can author YAML → get a green/red result on a real template with zero Ruby. ✅
+
+---
+
+## Phase 2 — Reporters + more check primitives + CLI  ✅ MOSTLY DONE 2026-07-03 (branch `feature/phase-2`, commit `22cc865`)
+
+- [x] `Reporters::Csv` + `Reporters::Html` (derive from the canonical Result). JSON/Text refactored
+  to render from the canonical hash so redaction applies uniformly.
+- [x] More checks: field ordering + section ordering, force/binding presence, select-option weights,
+  field-count bounds (exact or `{min,max}`), "must NOT exist" (stage/section/field absent),
+  regex on labels (`label_pattern`, optional `type`). Force/option/required checks `skip` honestly
+  when the snapshot didn't capture them.
+- [!] Capture the reference template `6a3fa5b8…622b` via the gem's `dump_template_model.rb`; pin as
+  a fixture + author a real check-set. **BLOCKED on a sandbox org + creds** (Open Q #2). Substituted
+  a synthetic `sample_template_page.json` (real doc shape) to exercise the new checks offline.
+- [x] PII-redaction pass on results (`Redactor` — emails + custom patterns; preserves verdict/counts).
+- [x] `exe/ecoportal-qa run <check-set> --source fixture:PATH|graphql:ID [--format ...] [--redact]`
+  CLI; exit code encodes verdict for CI (0/1/2/3).
+
+31 specs green, rubocop clean. Only the live-capture item remains (creds-blocked).
+
+## Phase 2b (carried) — monitoring hookup
+- [ ] Feed the canonical Result JSON into a dashboard/monitoring sink (design alongside Phase 4 CI).
+
+## Phase 3 — Jira adapter (human-gated)  — SCOPED 2026-07-03 (see `PHASE3-SCOPE.md`)
+
+**Blocked on build** until Oscar answers the 4 open questions in PHASE3-SCOPE.md (Jira project +
+workflow statuses; REST token vs MCP-only; verdict field vs comment-only; where check-sets live).
+
+- [~] Design complete — `Jira::{Client,RestClient,McpClient,DryRunClient,Publisher}`; result funnels
+  in as just another consumer of the canonical Result (no runner/DSL changes).
+- [x] **3a** — `Jira::Client` interface + `DryRunClient` + `Publisher` (render→redact→idempotent
+  comment). Offline-specable (DryRunClient records calls). *DONE 2026-07-03, branch
+  `feature/qa-jira-3a-dryrun-publisher` (ecoportal-qa, UNMERGED). 21 new specs (52 total), rubocop
+  clean. Report-only default (no transition), redact-before-post, per-ticket idempotency marker,
+  audit trail. 3b/3c still blocked on the 4 open Qs (Jira project/statuses, REST token vs MCP,
+  verdict field, where check-sets live).*
+- [ ] **3b** — `Jira::RestClient` (base URL + service-account token; env-gated integration spec).
+- [ ] **3c** — CLI `report --jira [--jira-client rest|mcp|dry-run] [--transition NAME] [--attach ...]`
+  + audit log. Default = report-only (no transition); `--transition` is explicit + human-invoked.
+- [ ] **3d** — (optional) `Jira::McpClient`.
+- [x] Decision recorded: interface + REST-first, MCP later; Phase 3 never auto-transitions (DECISIONS).
+
+## Phase 4 — CI-as-code backend ("ticket as pipeline")
+
+- [ ] Compiler backend: emit a CI job (GitLab CI / GH Actions) from a check-set.
+- [ ] Pipeline-per-ticket: on ticket state, run the check-set, archive the Result artifact.
+- [ ] Monitoring/dashboards fed by the canonical Result JSON.
+
+## Phase 5 — Opt-in auto-approve hooks (governed)
+
+- [ ] QA-owned rule: `verdict == passed` + explicit opt-in → offer/perform an auto-transition.
+- [ ] Off by default; audit every auto-approval; RBAC on who can enable it.
+
+---
+
+## Open questions (Oscar)
+1. Which Jira project(s)/workflow are we targeting, and MCP vs REST for the adapter?
+2. Sandbox org + creds to run `GraphqlSource` / capture `6a3fa5b8…622b` live.
+3. Do QA prefer authoring in YAML or JSON (both parse the same) — and where do check-sets live
+   (in `ecoportal-qa/qa/checks/`, per-customer repos, or a shared config repo)?
+4. Publish `ecoportal-qa` to the internal gem registry, or keep it path/git-sourced for now?