ecoportal-api-graphql 1.3.13 → 1.3.16

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

@@ -1,93 +0,0 @@
-# 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

@@ -1,76 +0,0 @@
-# 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

@@ -1,115 +0,0 @@
-# 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

@@ -1,99 +0,0 @@
-# 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

@@ -1,81 +0,0 @@
-# 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/search-filter-builder/INTENT.md

@@ -1,107 +0,0 @@
-# Project: Search Filter Builder
-
-**Created:** 2026-06-07
-**Status:** Planning
-
----
-
-## Problem
-
-The EcoPortal GraphQL `searchConf` argument is a Hash type — not a typed GraphQL input
-model. This means:
-- No schema validation or autocomplete for filter structures
-- Scripts must hand-craft raw hashes, which are error-prone and hard to read
-- No reuse: changing a search target (e.g. a different `externalId`) requires cloning
-  and mutating the whole hash manually
-- No discoverability: customers have no way to learn available filter fields from the
-  schema — they must consult separate documentation
-
-Engineering has backend classes for the search model, but these are not exposed as
-GraphQL input types. The Confluence API Docs space has a partial filters reference, but
-it is incomplete and not tied to any code.
-
----
-
-## Goal
-
-Provide a first-class Ruby filter builder in `ecoportal-api-graphql` that:
-
-1. **Mirrors backend structure** — classes that correspond to the backend search model,
-   even though they have no GraphQL type equivalent (they serialise to the expected Hash).
-2. **Supports AND/OR composition** — clean DSL to express nested filter logic without
-   manually constructing the `or:` / `filters:` nesting.
-3. **Supports parametrization** — re-use a filter template by substituting specific
-   values (e.g. swap `externalId`, `locationId`, field value) without re-building
-   from scratch each call.
-4. **Works for both search modalities:**
-   - Org search: `currentOrganization { pages(searchConf: ...) }`
-   - Register search: `currentOrganization { register(id:) { pages(searchConf: ...) } }`
-5. **AI assistance hook (future):** The front-end already has AI-generated filter
-   construction for end users. This builder should be designed so that a future AI layer
-   can generate filter objects from natural-language descriptions. The structured classes
-   make this tractable — the AI outputs typed objects rather than raw hashes.
-
----
-
-## Context
-
-### searchConf structure (verified from Insomnia production queries)
-
-```json
-{
-  "filters": [ <filter_object>, ... ],
-  "sorters": { "key": "created_at", "direction": "asc" },
-  "query":   "optional full-text string"
-}
-```
-
-`filters` can be an array (standard) or a single object (older queries).
-`sorters` can be a single object or an array. Key field is `key` (not `fieldName`).
-
-### Filter operations (snake_case strings — confirmed)
-
-| Operation | Structure | Notes |
-|---|---|---|
-| `exact_filter` | `{ key: "field", value: "val" }` | Equality match |
-| `date_filter` | `{ key: "field", gte: "ISO8601", time_zone: "UTC" }` | Also: `lte` |
-| `register_filter` | `{ ids: ["id1", "id2"] }` | Org search only — scope to registers |
-| `and_filter` | `{ filters: [...] }` | Explicit AND group (implicit at top level) |
-| `or_filter` | `{ filters: [...] }` | OR group |
-
-Additional (from Confluence docs, not yet confirmed via Insomnia):
-`in_filter`, `range_filter`, `exists_filter`, `ne_filter`
-
-### Known filter key fields (confirmed from Insomnia)
-
-| key | Type | Operations confirmed |
-|---|---|---|
-| `external_id` | string | `exact_filter` |
-| `updated_at` | datetime | `date_filter` |
-| `created_at` | datetime | (in sorters; likely filterable too) |
-
-Additional (from Confluence docs): `state`, `location_ids`, `creator_id`, `template_id`
-
-Full reference with production examples: `.ai-assistance/code/search_filters.md`
-
-### Source references
-
-- Insomnia v5 export: pending import into `.ai-assistance/tmp/insomnia_searches.json`
-- Backend filter classes: accessible via the ecoPortal Rails codebase
-- Front-end queries: `.graphql` files distributed across the React codebase hierarchy
-- Confluence APIDOCS: partial filter reference (most common filters section)
-
----
-
-## Design principles
-
-- **No GraphQL type required:** Builder classes serialise to Hash — they are plain Ruby
-  value objects, not GraphQL input classes. No `Logic::Input` inheritance needed.
-- **Composable:** `AndFilter`, `OrFilter`, `Filter`, `Sorter`, `SearchConf` as
-  distinct classes. Compose like: `SearchConf.new.where(externalId: 'X').or(state: :active, state: :draft)`.
-- **Parametrizable:** A built `SearchConf` can be cloned with substitutions —
-  `search.with(externalId: 'Y')` returns a new instance with one value swapped.
-- **Serializes to Hash:** `search.to_h` returns the raw hash ready to pass as
-  `searchConf:` argument to any query.
-- **AI-compatible (future):** Class structure is simple enough for an AI model to
-  instantiate from a natural-language description. The AI assistance integration
-  is a follow-on — design should not be blocked by it.