ecoportal-api-graphql 1.3.10 → 1.3.12

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,87 @@
+# 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`
+**Governing security standard (read before wiring live creds):** `security/ai-service-account-scope`
+in ep-ai-standards. This automation MUST authenticate as a dedicated per-org SERVICE ACCOUNT whose
+grant covers templates/org-config only -- page records (customer data + PII) are structurally out of
+scope, enforced by the credential grant, not by instruction. This is the practitioner discovery point
+for that standard (the template automation is its concrete consumer). The "sandbox creds" in success
+criterion #4 below must be provisioned to that scope. Platform dependency RESOLVED: templates ARE pages
+(`PageUnion`), but `stage.tags` (wrongly deprecated ~21 months ago) has been restored via ecoPortal MR
+!6649, so a rule scoped to template stages can structurally exclude record stages. Defining and
+provisioning the concrete grant is now OUR work (this gem + agent), not a platform blocker -- see the
+service-account grant task in `TODO.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.

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

@@ -0,0 +1,108 @@
+# TODOs — Template Automatic Build & Maintenance  ★ #1 PRIORITY
+
+Legend: `[ ]` todo · `[~]` in progress · `[x]` done · `[!]` blocked
+Domain reference: `.ai-assistance/code/template_diff_pairing_domain.md`
+Code spec: `.ai-assistance/code/diff_pairing_engine.md`
+
+This merges the former `template-diff-deploy/TODO.md` (MAINTAIN track) and
+`template-maintenance/DESIGN.md`+`PHASE0-FINDINGS.md` (BUILD track). BUILD and DIFF-DEPLOY share ONE
+emission layer: an ordered `WorkflowCommand` batch with `placeholderId` threading.
+
+---
+
+## MAINTAIN track (diff → deploy → verify → monitor)
+
+### Phase 1 — Self-version diff (same object, exact)  ✅ DONE
+- [x] `Diff::VersionDiff` — two same-id snapshots → structured changelog (stages/sections/fields/options).
+- [x] `Diff::Change` — command-ready (op/kind/id/before/after) + human `#description`.
+
+### Phase 2 — Expose genome + Change→commands  ✅ DONE
+- [x] `genomeSignature` on the data-field fragment + `Base::Page::DataField` (`passthrough`).
+- [x] `Diff::CommandSynthesizer` — `[Change]` → ordered built `WorkflowCommand` batch; edit-mode moves
+  gated on `Diff::IdResolver`; type change / resolver-less move → UNSUPPORTED (never guessed).
+- [x] `Diff::Deploy` — `from_versions(before, after, target_doc:)`; `#execute!` gates on `unsupported`.
+
+### Phase 3 — Pairing engine (equivalence)  ✅ DONE
+- [x] `Diff::Pairing::Engine` + `Signals` (genome 0.5 / type 0.2 / label 0.2 / options 0.1), greedy 1:1,
+  auto-accept ≥0.85 unless near-tie, ambiguous 0.5–0.85, unmatched <0.5; genome fallible (0 not veto).
+- [x] `Diff::Pairing::Ledger` — persisted confirmed pairs (consulted first; supersede-on-correct).
+- [x] `Engine#confirm!(candidate, matched_by: :human)` assisted-resolution hook.
+- [ ] TODO (eco-helpers): interactive assisted-resolution UX; `TypedFieldsPairing` as an extra signal;
+  live A/B parity harness.
+
+### Phase 3b — Gauge-stop + typed byType config emission + placeholderId threading  ✅ DONE
+- [x] `VersionDiff` emits `:gauge_stop` + `:field_config` (byType, data-driven `BYTYPE_CONFIG`,
+  conservative — only confirmed read↔byType-key matches; unmappable props NOT fabricated).
+- [x] `CommandSynthesizer` maps them; `thread_placeholders:` id-threading primitive (Deploy → on).
+
+### Phase 4 — Diff modalities (composable strategies)  ✅ DONE 2026-07-04 (branch `feature/template-phase4-modalities-builder-docs`)
+- [x] `Diff::Strategy` value object over the four axes: pairing `:id|:genome|:type_label|:assisted` ×
+  scope `:structural|:config_only|:data_migration` × move-sensitivity × intent
+  `:changelog|:deploy|:sync_readiness`. Validates axes; `#filter(changes)` applies scope +
+  move-sensitivity; `.default` reproduces the pre-Phase-4 self-version behaviour EXACTLY (BC).
+- [x] `VersionDiff.new(before, after, strategy:)` — the `:id` front-end now filters its computed
+  change-set through the strategy (default = unchanged; specs prove BC + config_only + move-insensitive).
+- [x] `Diff::CrossObjectDiff` — the CROSS-OBJECT front-end: pairs FIELDS via `Pairing::Engine` (+ optional
+  `Ledger`), builds the id-correspondence map from the ACCEPTED pairs, then emits the SAME `Change`
+  output (relabel/retype on paired fields; target-only → :added; confidently-unpaired source → :removed).
+  Ambiguous/unmatched (incl. same-genome relabels + near-ties) are held in `#unresolved` for a human —
+  NEVER auto-paired, auto-added, or auto-removed. Feeds `CommandSynthesizer`/`Deploy` unchanged.
+- [x] `Deploy.from_cross_object(source, target, engine:, strategy:)` + `Deploy#pairing` (exposes
+  accepted/ambiguous/unmatched for adjudication before apply).
+- [x] Specs: `strategy_spec` (16), `cross_object_diff_spec`, `version_diff_modalities_spec`. Full diff
+  suite 120 examples (was 93; +27). Rubocop clean.
+
+### Phase 5 — Deploy + verify + monitor  (NEXT)
+- [ ] UAT→PROD replay end-to-end: pair → diff → delta commands → apply → verify via `ecoportal-qa`.
+- [ ] Pre/post self-version diff on PROD to confirm the recreation matches the intended delta.
+- [ ] Sync-readiness monitoring: which registers/subsets can sync to their active template.
+
+---
+
+## BUILD track (build-from-scratch → verify)
+
+### Phase B0 — Study & capture  ✅ DONE (see `template-maintenance/PHASE0-FINDINGS.md`)
+- [x] `Builder::Template#create/update(commands:)` + `Input::WorkflowCommand` are the apply facade.
+- [x] `placeholderId` is the id-threading primitive (client-chosen, resolved intra-batch).
+- [x] `tests/dump_template_model.rb` captures a template's structural page doc; reference target
+  `6a3fa5b8f89e07c758df622b` (needs sandbox creds to run live).
+
+### Phase B1 — Gem-level BUILD emitter (unified with diff)  ✅ DONE 2026-07-04 (branch `feature/template-phase4-modalities-builder-docs`)
+- [x] `Builder::TemplateBuilder` — declarative spec (stages→sections→fields→options→config→gauge-stops)
+  → ordered `WorkflowCommand` batch, `placeholderId`-threaded. Order: addStage → addSection →
+  addStageSection → editSectionHeader → addField → addSelectFieldOption / addGaugeFieldStop /
+  editFieldConfiguration(byType:). Verified against `Builder::Template#create/update(commands:)` + the
+  real input classes' VALID_KEYS (only valid keys emitted; nothing fabricated — config passed through
+  under its byType sub-hash exactly as supplied). Shares the SAME `placeholderId` threading concept as
+  `Diff::CommandSynthesizer`. 13 specs. Rubocop clean.
+- [ ] UNSUPPORTED/deferred here (honest): forces/strategies/callbacks/tasks/recipients in a build spec
+  (the command inputs exist but the build spec shape for them was not confirmed — add per confirmed
+  shape); `field_type` enum values not validated against the schema (passed through as given).
+
+### Phase B2 — Live characterization  (NEXT, needs sandbox)
+- [ ] Replay `TemplateBuilder` output to reconstruct sample `6a3fa5b8…622b`; assert structure-equivalence
+  vs the pinned `dump_template_model.rb` fixture. `executeWorkflowCommands` mutates → sandbox, not CI.
+
+### Phase B3 — CSV→templates pipeline  (later, deadline ~Sept 2026)
+- [ ] CSV extract → `TemplateBuilder` spec → build batch, for the 300+ template delivery. Section/field
+  identity via hidden-field + description (see memory: project-template-csv-pipeline).
+
+---
+
+## Cross-cutting
+- [ ] **Service-account grant (gates live use; governed by ep-ai-standards `security/ai-service-account-scope`).**
+  This automation must run as a dedicated per-org SERVICE ACCOUNT scoped to templates/org-config only --
+  page records out of scope, enforced by the grant (structural PII/compliance boundary, not instruction).
+  Platform enabler is in place: `stage.tags` (wrongly deprecated ~21 months ago) restored via ecoPortal
+  MR !6649, so a rule scoped to template stages can exclude record stages. OUR remaining work:
+  (a) enumerate in-scope object types (templates; and which of registers / stages / tag defs / workflow +
+  automation config / custom-field defs -- explicit in/out per type, each a potential path back to records);
+  (b) write the concrete `stage.tags` rule and confirm no record stage shares those tags;
+  (c) fix the read/write surface per type (edit templates? read-only org-config?);
+  (d) provision the per-org account and confirm its `canXXX` set carries NO page-record capability.
+  Feeds the "sandbox creds" needed by Phase B2 / Phase 5. Reference: INTENT header + the standard.
+- [ ] Tighten `ecoportal-qa` to consume the gem's page-model instead of its own `TemplateModel`.
+- [ ] Emit `stageId`/`sectionId` back-refs on diff-side `addField`/`addSection` (BUILD already does;
+  the diff synthesizer's structural adds still emit only label/placeholder — then threading covers them).
+- [ ] Extend `BYTYPE_CONFIG` per field type as read↔byType-key shapes are confirmed; gauge-stop reorder.
+- [ ] Complete the `PagesWorkflow.stages` read model to unblock workflow-config-per-stage diff.

data/.ai-assistance/projects/template-diff-deploy/INTENT.md

@@ -0,0 +1,12 @@
+# MOVED → `template-automatic-build-maintenance`  ★ #1 PRIORITY
+
+This project has been **merged** into the unified **Template Automatic Build & Maintenance** project.
+
+- Single INTENT: `../template-automatic-build-maintenance/INTENT.md`
+- Single TODO:   `../template-automatic-build-maintenance/TODO.md`
+
+The MAINTAIN track (diff → deploy → verify → monitor) that lived here is now the "MAINTAIN track"
+section of the merged TODO. Nothing here is authoritative any more — do not update this folder.
+
+Domain reference (unchanged): `.ai-assistance/code/template_diff_pairing_domain.md`.
+Code spec (unchanged): `.ai-assistance/code/diff_pairing_engine.md`.

data/.ai-assistance/projects/template-diff-deploy/TODO.md

@@ -0,0 +1,9 @@
+# MOVED → `template-automatic-build-maintenance/TODO.md`
+
+The diff/deploy TODOs (Phases 1–5) are now the **MAINTAIN track** of the merged
+**Template Automatic Build & Maintenance** project (★ #1 priority):
+
+→ `../template-automatic-build-maintenance/TODO.md`
+
+Phases 1–3b + Phase 4 (diff modalities: `Diff::Strategy` + `CrossObjectDiff`) are DONE there.
+Do not add TODOs here.

data/.ai-assistance/projects/template-maintenance/PHASE0-FINDINGS.md

@@ -0,0 +1,93 @@
+# Template-Maintenance — Phase 0 Findings (2026-07-02)
+
+Ground-truth survey of the gem + eco-helpers surface, verified against actual code (not the
+DESIGN.md second-hand survey). Corrections to DESIGN.md assumptions are flagged **⚠**.
+
+---
+
+## 1. The gem mutation surface is MORE complete than DESIGN.md implied
+
+- **⚠ `Builder::Template` already exists and is wired** (`lib/ecoportal/api/graphql/builder/template.rb`,
+  exposed as `GraphQL#template`, `graphql.rb:98`). It offers:
+  `create(commands:)`, `update(model, commands:, patch_ver:)`, `publish(id:)`, `unpublish(id:)`,
+  `update_information(id:, ...)`, `create_related_page(...)`, `destroy_related_page(...)`.
+  → The template create/update **apply** step is done. We do **not** need to build a new facade
+  for `executeWorkflowCommands` on the template side — `Builder::Template#create/update` already
+  wrap `Mutation::Template::{Create,Update}` with a `commands:` array.
+- `Builder::Page#execute_workflow_commands` also exists (per `builder/CLAUDE.md`) for the
+  page-level workflow command path.
+- `Input::WorkflowCommand` (`input/workflow_command.rb`) is the command registry:
+  **108 commands** in `COMMAND_MAP`, `SCHEMA_VERSION = '20260605'`, with:
+  - `.build(command_key, **kwargs)` → `{ key => sliced_kwargs }` (validates key, slices to VALID_KEYS, compacts nils, keeps false)
+  - `.build_commands(specs)` → maps an ordered array of single-key specs into the batch
+  - `.valid_key?(key)`
+
+## 2. A template IS a page (read path)
+
+- **⚠ DESIGN.md Open Question #2 ("is PagesWorkflow read complete enough to diff a template?")
+  is partly moot for STRUCTURE.** `Query::Templates` returns `PageUnion` nodes with `PageFields`
+  — a template is read as an ordinary page. So the structural skeleton
+  (**stages → sections → components(fields)**) comes from the page model, exactly like a live page.
+  `dump_template_model.rb` therefore reuses `api.pages.get(id)` for structure.
+- The `PagesWorkflow` read model (`base/pages_workflow.rb`) is the **workflow-command config**
+  layer (callbacks, operations, triggers, strategies, recipients). **⚠ It is partial:** `stages`
+  is a bare `passarray` (no per-stage strategy/section tree). So:
+  - **Build-from-scratch (Phase 2): UNBLOCKED.** Emit commands, execute, read the page back to verify.
+  - **Structural diff (Phase 4): mostly UNBLOCKED** via the page model (stages/sections/fields).
+  - **Workflow-config diff (callbacks/strategies per stage): BLOCKED** on completing the
+    `PagesWorkflow.stages` read model. Track as a Phase-4 dependency, not a Phase-2 blocker.
+- Forces read is on the page model but `Query::PageWithForces` is WIP (see forces notes) — a
+  forces-aware diff is a later dependency.
+
+## 3. `placeholderId` is the id-threading primitive (the key design fact)
+
+The location-structure engine threads server-assigned ids **post-hoc** (zip input↔result, extract
+`newId`, remap table). **The workflow command bus does NOT need that** — it uses **client-chosen
+`placeholderId`s resolved intra-batch**:
+
+| Command | Placeholder it defines | References (by placeholder or real id) |
+|---|---|---|
+| `addStage` | `placeholderId` | — |
+| `addSection` | `placeholderId` | — |
+| `addStageSection` | — | `stageId`, `sectionId` |
+| `addField` | `placeholderId` | `stageId`, `sectionId`, `column` |
+| `addSelectFieldOption` | `placeholderId` | `dataFieldId` |
+| `addForce` | `placeholderId` | — |
+| `addBinding` | `placeholderId` | `forceId` |
+
+→ The emitter assigns a stable `placeholderId` to every new node and references it downstream in
+the **same batch**. This is simpler than the location `track_changed_ids` remap. **⚠ Correction to
+DESIGN.md:** we mirror the location engine's *shape* (DSL → ordered commands → apply → read-back),
+but the id-threading is placeholder-based, not `newId`-remap-based.
+
+**Open question to confirm live:** does `executeWorkflowCommands` resolve placeholderIds across the
+*whole* batch, or only within ordering constraints (e.g. must addStage precede addStageSection)?
+The emitter already emits in dependency order (stage → section → stageSection → field → option),
+so this is safe either way; confirm during the Phase-3 sandbox replay.
+
+## 4. What Phase 0 delivered (this commit)
+
+- `tests/dump_template_model.rb` — captures a template's structural page doc
+  (`spec/fixtures/templates/<id>.json`) + best-effort workflow command log
+  (`<id>.commands.json`). Mirrors `dump_page_model.rb`; run `--label before/after` around a batch
+  to diff. **Reference target:** sample `6a3fa5b8f89e07c758df622b` (needs a live/sandbox org to run).
+- `spec/.../input/workflow_command_serialization_spec.rb` — offline serialization contract for the
+  structural command families + the `build_commands` ordered-emitter shape + placeholderId threading.
+  10 examples, green. This is the net the eco-helpers emitter is written against.
+
+## 5. Revised phase view
+
+- **Phase 1 (gem):** DONE-ENOUGH. `Builder::Template` + `Input::WorkflowCommand` are the facade;
+  offline command specs exist and grow as new command types are exercised.
+- **Phase 2 (eco-helpers):** `samples/pages/template/{base,dsl}.rb` + a command-emitter service
+  (DSL → ordered commands w/ placeholderId threading → `Builder::Template#create/update` → read-back).
+  Offline emitter specs are fully achievable without live calls.
+- **Phase 3 (sandbox):** replay to reconstruct `6a3fa5b8…622b`; assert structure-equivalence vs the
+  `dump_template_model.rb` fixture. Needs a sandbox org (Open Question #1 — creds TBD).
+- **Phase 4 (diff):** structural diff via page model now; workflow-config diff waits on the
+  `PagesWorkflow.stages` read model.
+
+## Open questions still owned by Oscar
+1. Sandbox org + creds for the Phase-3 live characterization harness.
+2. Priority of completing the `PagesWorkflow.stages` read model (gates workflow-config diff).
+3. Does `6a3fa5b8…622b` exercise forces? (gates the forces read/write split for its replay)

data/.ai-assistance/projects/template-maintenance/README.md

@@ -0,0 +1,14 @@
+# MOVED → `template-automatic-build-maintenance`  ★ #1 PRIORITY
+
+This project has been **merged** into the unified **Template Automatic Build & Maintenance** project.
+
+- Single INTENT: `../template-automatic-build-maintenance/INTENT.md`
+- Single TODO:   `../template-automatic-build-maintenance/TODO.md`
+
+The BUILD track (build-from-scratch → verify → CSV pipeline) that lived here is now the "BUILD track"
+section of the merged TODO. The gem-level BUILD emitter is DONE
+(`Builder::TemplateBuilder`, shares the diff's `placeholderId` emission layer).
+
+`DESIGN.md` and `PHASE0-FINDINGS.md` are RETAINED here as background — the merged INTENT/TODO reference
+them for the survey + the `placeholderId` id-threading facts. They are historical context, not the
+active task list. Do not add new TODOs here — use the merged TODO.