ecoportal-api-graphql 1.3.10 → 1.3.11

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?

data/.ai-assistance/projects/template-automatic-build-maintenance/INTENT.md

@@ -0,0 +1,77 @@
+# Project: Template Automatic Build & Maintenance  ★ #1 PRIORITY
+
+**Status:** ACTIVE — the #1-priority project. **Created:** 2026-07-04 (merges the former
+`template-diff-deploy` + `template-maintenance` projects into one plan).
+**Domain reference (read first):** `.ai-assistance/code/template_diff_pairing_domain.md`
+**Code spec:** `.ai-assistance/code/diff_pairing_engine.md`
+**Superseded folders (pointers only now):** `template-diff-deploy/`, `template-maintenance/`.
+**Sibling projects:** `qa-services-delivery` (verify), `ooze-graphql-native-migration`,
+`template-csv-pipeline` (memory).
+
+---
+
+## Why this is one project
+
+Both former projects are two halves of the SAME lifecycle and share ONE emission layer (an ordered
+`WorkflowCommand` batch with `placeholderId` threading applied to `executeWorkflowCommands`):
+
+- **BUILD** (was `template-maintenance`) — build/maintain 300+ templates programmatically
+  (CSV→templates pipeline, deadline ~Sept 2026): declare a desired template → emit an ordered command
+  sequence → apply → read back to verify.
+- **MAINTAIN / DIFF-DEPLOY** (was `template-diff-deploy`) — make UAT→PROD change replication smooth:
+  detect (diff) → review → deploy (delta commands) → verify → monitor, eliminating the two manual
+  regressions (lost PROD-only changes; premature release of unapproved UAT changes).
+
+BUILD is "add everything"; DIFF-DEPLOY is "add/remove/edit only the delta". Same command vocabulary,
+same id-threading, same apply path. Keeping them as one project keeps the emission layer unified.
+
+## The core hard problem (unchanged)
+
+No stable identity across independent Mongo objects (template vs child page, UAT vs PROD). Self-version
+diff (same ids) is trivial and done; cross-object diff is an **equivalence-matching** problem — pair
+fields on multiple weak signals (genome + type + label + options), human-assisted for the ambiguous
+ones, with a persisted **learning ledger**. See the domain reference for the full failure-mode map.
+
+## Approach (confirmed)
+
+- **Self-version diff first** (done) — the portable "commit".
+- **Pairing = equivalence matching**, not identity — multi-signal, confidence-scored, human-in-loop,
+  ledger-backed (`Diff::Pairing::Engine` + `Ledger`; also feeds Product's Field-ID / template-entity-id).
+- **Diff MODALITIES** — a composable family, NOT one diff: `Diff::Strategy` over four axes
+  (pairing `:id|:genome|:type_label|:assisted` × scope `:structural|:config_only|:data_migration` ×
+  move-sensitivity × intent `:changelog|:deploy|:sync_readiness`). `VersionDiff` is the `:id`
+  front-end; `CrossObjectDiff` is the cross-object front-end (pairs fields, emits the SAME `Change`
+  output against the pairing map, consumed by the existing synthesizer/deploy unchanged).
+- **Unified BUILD emitter in the gem** — `Builder::TemplateBuilder` turns a declarative spec into the
+  ordered `WorkflowCommand` batch (stages→sections→fields→options→config→gauge-stops), threading
+  `placeholderId`s exactly as `Diff::CommandSynthesizer` does. BUILD and DIFF-DEPLOY share one layer.
+- **Layering** — mechanics (read model, command vocab, build emitter, diff, apply, pairing engine +
+  ledger) live in the gem so admin/troubleshooting/integration/QA all reuse them; orchestration
+  (interactive assisted-resolution UX, session flows, `TypedFieldsPairing` as an extra signal) is in
+  eco-helpers.
+
+## The pipeline
+
+```
+BUILD:     desired spec ─► TemplateBuilder ─► ordered WorkflowCommands ─► Builder::Template#create/update ─► verify
+MAINTAIN:  pair (id|genome|type_label|assisted+ledger) ─► diff (modality) ─► delta WorkflowCommands
+                 ─► Deploy#execute! (gated on `unsupported`) ─► verify (ecoportal-qa) ─► monitor (sync-ready)
+```
+
+## Scope
+
+- In: self-version diff (done); genomeSignature exposure (done); pairing engine + ledger (done); diff
+  modalities/Strategy (done); cross-object diff path (done); Change→WorkflowCommands synthesis (done);
+  gem-level BUILD emitter (done); UAT→PROD replay; sync-readiness monitoring; CSV→templates pipeline
+  (later); tighten `ecoportal-qa` to consume the gem's page-model.
+- Out: waiting on Product's template-entity-id (we bridge + feed it); auto-applying without human
+  review of unresolved pairings; workflow-config-per-stage diff until `PagesWorkflow.stages` read model
+  is completed (see `template-maintenance/PHASE0-FINDINGS.md` §2).
+
+## Success criteria
+
+1. A ticket's UAT changes are captured exactly and rendered as a review checklist (self-version). ✅
+2. Two templates diff correctly with pairing; unresolved pairings are escalated to a human + remembered. ✅ engine + cross-object path ready; interactive UX pending (eco-helpers).
+3. A reviewed delta deploys to PROD as WorkflowCommands, then is verified (ecoportal-qa) — no regressions.
+4. A template can be BUILT from a declarative spec via one ordered command batch. ✅ emitter ready; live characterization pending (sandbox creds).
+5. Monitoring shows which registers/subsets are sync-ready to their active template.