ecoportal-api-graphql 1.3.13 → 1.3.16

data/.ai-assistance/projects/search-filter-builder/TODO.md

@@ -1,131 +0,0 @@
-# TODOs — Search Filter Builder
-
-> Natural order: 1 → 2 → 3 → 4 → 5. Step 1 unblocks everything else.
-
----
-
-## Step 1 — Ground truth: gather filter fieldNames and operator examples
-
-- [x] **1.1** Insomnia v5 export reviewed — all search patterns documented in
-  `.ai-assistance/code/search_filters.md`. Confirmed operations: exact_filter,
-  date_filter, register_filter, and_filter, or_filter (all snake_case).
-  *Done 2026-06-07*
-
-- [x] **1.2** Backend filter classes read — `app/services/new_ep/es/filters/`.
-  Key findings: 29 global filter operations via dynamic class routing (operation →
-  `"#{op.camelize}Filter"` class name); no central whitelist — filters auto-discovered.
-  Page-specific fieldNames: external_id, state, name, creator_id, created_at, updated_at,
-  template_id, id, location_id, all_location_ids, other_tags, archived, draft, mould_counter.
-  Full human date mode list extracted from `HumanDateFilterable` concern.
-  *Done 2026-06-08*
-
-- [x] **1.3** Frontend `.graphql` + `createFilter.ts` swept — 159 unique operations found.
-  New operations confirmed beyond prior Insomnia list: `one_of_filter`, `none_of_filter`,
-  `has_any_filter`, `match_filter`, `exists_filter`, `doesnt_exist_filter`, `boolean_filter`,
-  `numeric_range_filter`, `isnt_exact_filter`, `not_register_filter`.
-  Confirmed `in_filter`/`range_filter`/`ne_filter` are NOT real operations.
-  *Done 2026-06-08*
-
-- [x] **1.4** `search_filters.md` extended with:
-  - Full fieldName reference table for Pages (core metadata, location, tag, boolean fields)
-  - Extended operation reference (15 confirmed operations including new ones)
-  - Human date mode table (30+ modes from HumanDateFilterable)
-  - Parametrization patterns section (SearchConf#with — 3 examples)
-  - Updated Filter Builder constants with confirmed/denied status
-  *Done 2026-06-08*
-
----
-
-## Step 2+3 — Design + Implement (Done 2026-06-07)
-
-- [x] **2.1+3.1** Implemented `Input::SearchConf` with nested filter classes:
-  `SearchConf::Exact`, `SearchConf::DateRange`, `SearchConf::Register`,
-  `SearchConf::And`, `SearchConf::Or`. Plain Ruby value objects, no Logic::Input.
-  Chainable builder, `to_h` serialises to the expected Hash structure.
-  `as_json` support for transparent JSON serialisation.
-  *`lib/ecoportal/api/graphql/input/search_conf.rb`*
-
-- [x] **2.2+3.3** Parametrization via `#with(**substitutions)` — returns a cloned
-  `SearchConf` with substituted values propagated into nested filters.
-  *Confirmed immutable (original not mutated)*
-
-- [x] **4.1** 23 RSpec specs covering all filter types, builder methods, sorter
-  single/array convention, parametrization, nested Or propagation, as_json.
-  *`spec/ecoportal/api/graphql/input/search_conf_spec.rb`*
-
-## Remaining
-
-- [x] **3.4** Wire `SearchConf` acceptance into queries — implemented via
-  `Logic::BaseQuery#normalize_variables`: auto-calls `.to_h` on any value responding to `to_h`
-  before passing as GraphQL variables. All queries accept `SearchConf` directly.
-  *Done 2026-06-07 (commit cc72902)*
-
-- [ ] **5.1 — Fluent DSL (future):** Replace the explicit constructor API with a fluent
-  operator-based DSL using Ruby's `&` (AND) and `|` (OR) operators — similar to how
-  Arel/Sequel work. Proposed syntax:
-
-  ```ruby
-  # Simple field predicate
-  Search[:external_id].eq('ABC')
-  Search[:updated_at].since('2025-01-01')
-  Search[:state].is(:active)
-
-  # Compound (& = AND, | = OR — operator precedence is natural)
-  Search[:external_id].eq('ABC') & Search.in_register('REG_ID')
-
-  Search[:state].is(:active) | Search[:state].is(:draft)
-
-  # Complex: register + date AND (state active OR draft)
-  Search.in_register('REG_ID') &
-  Search[:updated_at].since('2025-01-01') &
-  (Search[:state].is(:active) | Search[:state].is(:draft))
-
-  # Parametrize via .with
-  base = Search[:external_id].eq('X') & Search.in_register('REG')
-  copy = base.with(external_id: 'Y')
-  ```
-
-  Implementation: `Search[]` returns a `FieldRef` object; `.eq`, `.is`, `.since`,
-  `.contains` return filter value objects; `&` and `|` return `And`/`Or` composites.
-  Everything still serialises via `to_h`. The current explicit API (`SearchConf::Exact.new`)
-  remains as the foundation — the DSL is a layer on top.
-
-  **Why operator-based over method-chain (`filter.or.attr.label.contains(...)`):**
-  - `&`/`|` have natural Ruby precedence — parentheses control grouping as expected
-  - No ambiguity between "start a new filter" vs "modify current filter"
-  - Composable: any sub-expression can be stored in a variable and reused
-  - Familiar to developers who know Arel, Sequel, or Mongoid
-
-  **AI-generation hook:** The structured DSL makes AI output easy to validate —
-  the AI emits `Search[:field].op(value)` expressions that can be parsed/verified
-  before execution.
-
-## ~~Steps 2–4~~ — Done (superseded by implementation)
-
-Steps 2–4 were planning artefacts written before implementation. All are complete:
-- `SearchConf`, `SearchConf::Exact/DateRange/Register/And/Or/RawFilter` — implemented
-- `#to_h`, `#with`, `normalize_variables` auto-`to_h` — implemented
-- 23 RSpec specs covering all types — implemented
-- `search_filters.md` code-spec — implemented
-- Fluent DSL (`SearchConf[:field].eq(v)`, `&`, `|`) — implemented 2026-06-08
-
----
-
-## Step 5 — AI filter generation
-
-- [x] **5.1** Prompt template designed — system prompt in `SearchConf::AIGenerator::SYSTEM_PROMPT`:
-  all 13 operations with params, 11 page fieldNames with types/values, snake_case rule,
-  instruction to use `date_filter mode:` for relative dates.
-  *Done 2026-06-09*
-
-- [x] **5.2** `SearchConf.from_description(text, api_key:, model:, register_id:, context:, validate:)`.
-  Claude tool use (structured output via `build_search_conf` JSON schema).
-  `SearchConf::AIGenerator` in `input/search_conf/ai_generator.rb`.
-  Lazy require — `anthropic` gem not a hard dependency; helpful LoadError if missing.
-  `.env` loaded automatically in `spec_helper.rb` via dotenv.
-  Live tests tagged `:live`: `bundle exec rspec ...ai_generator_spec.rb --tag live`
-  *Done 2026-06-09*
-
-- [ ] **5.3** Evaluate: compare AI-generated filters against hand-crafted equivalents
-  using the Insomnia sample set as ground truth. Run live tests, collect outputs,
-  compare to manually built `SearchConf` instances.

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

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

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

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

@@ -1,9 +0,0 @@
-# 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/DESIGN.md

@@ -1,134 +0,0 @@
-# Template-Maintenance Tooling — Design & Scoping
-
-**Status:** DESIGN ONLY — not started. Implementation deferred until after the backwards-compat
-cutover release. This doc scopes the work so the AI agent (integrations agent) can pick it up.
-**Owner:** Oscar. **Drafted:** 2026-07-02.
-
----
-
-## Why
-
-A customer delivery needs **300+ templates** built/maintained programmatically (deadline ~Sept
-2026 for the CSV→templates pipeline). We need a GraphQL-native way to **build and update templates
-(workflows)** — create stages/sections/fields/forces/strategies/etc., and later diff a desired
-template against a live one and apply only the delta.
-
-This is a **new, additive** capability. It has **no end-script dependencies** and does **not** touch
-the maintained cutover integrations (toocs-coding, cans-upsert, supplier-documents, and Travis's
-upcoming mitre10). **OozeRedirect stays for the APIv2-shaped cases.** Template editing needs **no
-backwards compatibility** — we rewrite it cleanly, reusing the *ideas* (not the code) proven for
-APIv2, and add specs (preventative — see "Testing philosophy").
-
-Can ship in the **same release** as the cutover fixes as long as it **loads** and **passes the tests
-we can gather** (no runtime coupling to existing scripts).
-
----
-
-## What already exists (survey, 2026-07-01/02) — this is "extend a pattern", not "build new"
-
-### Gem (`ecoportal-api-graphql`) — the mutation surface is largely built
-- **91** `input/workflow_command/*.rb` command inputs (stages, sections, fields, forces, bindings,
-  tasks, strategies, operations, recipients, callbacks, gauge stops, linked fields, select options…).
-- `input/workflow_command.rb` — `WorkflowCommand::COMMAND_MAP` registry (`SCHEMA_VERSION`).
-- `mutation/page/execute_workflow_commands.rb` — applies a command batch (`executeWorkflowCommands`).
-- `query/pages_workflow_commands.rb` + `base/pages_workflow*` — the workflow READ model.
-- `base/force.rb` — queues `editForce`/`addBinding` commands (forces ARE mutable via the command-bus;
-  see `.ai-assistance/code/ecoPortal_architecture/10_forces_workflow_builder.md`).
-
-### eco-helpers — the samples space + the diff→commands PRECEDENT
-- `lib/eco/api/usecases/graphql/samples/pages/{page,org_page}/{base,dsl}.rb` + `pages/CLAUDE.md` —
-  the **established sample convention**: each sample is a `base.rb` + `dsl.rb` pair. A template
-  sample slots in as `samples/pages/template/{base,dsl}.rb`.
-- `lib/eco/api/usecases/graphql/samples/location/command/{dsl,service,service/tree_update,results,
-  track_changed_ids}.rb` + `samples/location/service/tree_diff/convertible/*` — a **working
-  diff→apply-commands engine** for LOCATION STRUCTURE (which uses `location_structure/apply_commands`
-  in the gem). This is the architectural precedent to mirror for templates.
-  - **`track_changed_ids` is the hard part already solved:** newly created nodes get server-assigned
-    ids that *subsequent* commands must reference (a new stage's id feeds the addSection targeting it).
-    Template build has the identical id-threading problem — reuse this pattern, don't reinvent it.
-
----
-
-## Design: template editing = the location diff→commands engine, retargeted to workflow commands
-
-Mirror `samples/location/command` + `tree_diff`, but:
-- **Target model:** template/workflow (stages → sections → fields → forces/strategies/…) instead of
-  the location tree.
-- **Command vocabulary:** the 91 `WorkflowCommand` inputs instead of location `apply_commands`.
-- **Apply mutation:** `executeWorkflowCommands` instead of `applyCommands`.
-- **DSL home:** `samples/pages/template/{base,dsl}.rb`, following the existing `page`/`org_page` shape.
-
-Two capabilities, in order of need:
-1. **Build from scratch** — declare a desired template via the DSL → emit an ordered command sequence
-   (addStage → addSection → addField → …) → `executeWorkflowCommands`, threading server-assigned ids
-   between commands (`track_changed_ids` pattern) → read back to verify.
-2. **Diff & update** — read the live template's workflow structure, diff against the desired DSL,
-   emit only the delta commands (the eventual UAT→PROD `template-diff-deploy` need). Build (1) first;
-   (2) reuses the same command emitter + the tree_diff approach.
-
----
-
-## Reference target (the test/characterization anchor)
-
-Reconstruct **template sample `6a3fa5b8f89e07c758df622b`** step by step. Capture it once as a pinned
-fixture (a `dump_template` tool — extend `tests/dump_page_model.rb`'s approach to fetch the workflow
-structure via the `pages_workflow_commands`/`PagesWorkflow` read). Each construction step reproduces
-one piece of that sample; the fixture is the golden master to diff against.
-
----
-
-## Testing philosophy (aligned with how our devs actually work)
-
-NOT specs-first-as-design. Specs here are **preventative** (guard against future breakage), matching
-the team's practice. Two layers:
-1. **Offline serialization specs (CI-pure, fast):** each `WorkflowCommand` input → correct GraphQL
-   payload; the command emitter produces the right ordered sequence + id-threading for a given DSL.
-   Added incrementally as each command type is wired — regression net, not design driver.
-2. **Live characterization harness (sandbox org, NOT CI):** replay the command sequence to reconstruct
-   sample `6a3fa5b8…622b`, fetch the result, assert structure-equivalence vs the pinned fixture.
-   `executeWorkflowCommands` mutates server state, so this runs against a sandbox/dev org by hand,
-   not in CI. Doubles as the regression net for the 300+ template delivery.
-
-Specs go in **eco-helpers** (for the samples/pages layer) and in the gem (for command serialization).
-
----
-
-## Phases
-
-- **Phase 0 — Study & capture (read-only; no prod writes):** read the two precedents
-  (`samples/pages/{page,org_page}/{base,dsl}.rb` + `pages/CLAUDE.md`; `samples/location/command` +
-  `tree_diff`, esp. `track_changed_ids`); build `dump_template` + pin sample `6a3fa5b8…622b`; map which
-  of the 91 commands the sample needs.
-- **Phase 1 — Gem read-back + ergonomic execute facade:** confirm the `PagesWorkflow` read returns a
-  diff-able structure; ensure `executeWorkflowCommands` has a clean builder facade. Offline command
-  specs (incremental).
-- **Phase 2 — `samples/pages/template/{base,dsl}.rb` (build-from-scratch):** DSL → ordered command
-  emitter + id-threading → execute → read-back verify.
-- **Phase 3 — Characterization suite:** the sandbox replay-the-sample suite (one assertion group per
-  construction step) vs the Phase 0 fixture.
-- **Phase 4 — Diff & update:** read live template, diff vs desired, emit delta commands (reuses the
-  tree_diff approach). Feeds `template-diff-deploy` (UAT→PROD via changelog).
-- **Phase 5 — Ship:** rides the same release; gated only on "loads + passes gathered tests"; no
-  end-script deps; OozeRedirect untouched.
-
----
-
-## Constraints / guardrails
-- No runtime coupling to the maintained integrations; OozeRedirect is for APIv2 cases only.
-- `WorkflowCommandInput` API is **volatile** — design for change (thin, data-driven command mapping;
-  keep `SCHEMA_VERSION` in view).
-- Prefer capturing verified platform facts in the **shared** knowledge base (not machine-local memory)
-  — the forces-RCA lesson.
-
-## Open questions (for the implementing agent / Oscar)
-1. Sandbox org for the live characterization harness — which org/creds?
-2. Is the `PagesWorkflow` read complete enough to diff a full template, or are there gaps (like the
-   forces READ query `Query::PageWithForces`, which is WIP)?
-3. Command ordering/dependency rules — is there a canonical order the backend expects, or does
-   `executeWorkflowCommands` resolve intra-batch references? (drives the id-threading design)
-4. Does `6a3fa5b8…622b` exercise forces? If so, coordinate with the `force_support?` read/write split.
-
-## Related
-- `.ai-assistance/code/ecoPortal_architecture/10_forces_workflow_builder.md` (command-bus + forces)
-- Memory: post-cutover-priorities, project-template-csv-pipeline, project-template-diff-deploy,
-  project-template-update-architecture, project-workflow-space.

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

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

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