ecoportal-api-graphql 1.3.11 → 1.3.13

data/.ai-assistance/projects/template-model-logic/CATEGORY_CATALOG.md

@@ -0,0 +1,236 @@
+# Category Catalog — Composite Question Archetypes (FIRST DRAFT)
+
+> Companion to `DESIGN_NOTE.md`. This is the **closed first set** of concrete "category"
+> archetypes for ecoPortal templates. A category is a reusable composite question pattern —
+> a **parametrizable macro** authored once that compiles down into flat `fields + forces`.
+> Authoring-first (per DESIGN_NOTE §5b): every archetype here is expressible via the
+> shipped `WorkflowCommandInput` command bus write path.
+
+---
+
+## How archetypes compile to `fields + forces`
+
+An archetype is a macro. Given its parameters (labels, options, which effect), it emits an
+**ordered batch of `WorkflowCommand` inputs** — the same batch `Builder::TemplateBuilder`
+already produces. The expansion has two halves:
+
+1. **Structure** → `addField` (per dependent field, with `fieldType`/`label`/`stageId`/`sectionId`/`column`),
+   `addSelectFieldOption` (per option), `addGaugeFieldStop` (per gauge band),
+   `addSection`/`addStageSection` (when the archetype owns a whole revealable section),
+   and follow-up `editFieldConfiguration` for `description` (the identity/CSV token),
+   `tooltip`, and per-type `byType` config. Field structure is placeholder-threaded
+   (`placeholderId`) so intra-batch references resolve before the server assigns real ids.
+2. **Flow** → one or more **forces** bound to the dependent fields. A force is an AngularJS/Lisp
+   snippet (`addForce {name, customScript}`) plus `addBinding {forceId, fieldId, name}` per field
+   it reads or writes. The force encodes the answer→effect mapping: `show`/`hide`/`disable`/`clear`,
+   `select`/`set`, `add-tag`/`remove-tag`, `accent` (color), and matrix lookups. In the
+   **EPTIR flat IR** target this same flow is modelled declaratively as a JSON-Logic `when`
+   condition + a closed effect (`show_field`/`hide_field`/`show_section`/`set_required`/`set_value`/
+   `add_tag`), which is then lowered to a force snippet at compile time.
+
+> **Hard constraint (VERIFIED, `workflow-command-guide.md` §"Schema realities", `add_field.rb`):**
+> `required` cannot be set through the command bus **anywhere** — not on `addField`, not on
+> `editFieldConfiguration` top-level, not on any `byType` sub-input. So any archetype effect that
+> "makes a field required" MUST be realised as **force-level conditional-required** (the force
+> refuses to let the stage submit / flags the field), NOT as a static template `required` flag.
+> Every `required_when_shown` below means *force-enforced*, not *template-attribute*.
+
+---
+
+## Summary table
+
+| # | Name | Parent question | Core effect | Grounding |
+|---|------|-----------------|-------------|-----------|
+| 1 | `conditional-detail-select` | Select (single) | reveal + require detail field on chosen answer(s) | **Well-grounded** (DESIGN_NOTE worked example; `numeric_behaviour_select`, `Bay_change_options`) |
+| 2 | `yes-no-with-evidence` | Select (Yes/No) or Checklist | reveal File/ImageGallery (+ note) on "Yes" | **Well-grounded** (File/Image field types heavily used; special case of #1) |
+| 3 | `checklist-with-followup` | Checklist (multi) | each unchecked/"No" item reveals its own follow-up field | **Plausible** (Checklist type real; per-item force wiring inferred) |
+| 4 | `multi-select-fanout` | Select (multiple) | each selected option enables/disables its own section | **Well-grounded** (`replace_risk` `update-unit` per-`category` section enable/disable) |
+| 5 | `risk-matrix` | 2× Select (likelihood, consequence) | compute rating via lookup table → Gauge + level Select + color + risk tags | **Well-grounded** (`replace_risk_case.rb` production force; `update_severity_force`) |
+| 6 | `select-drives-gauge` | Select (single) | map chosen option → numeric Gauge value + band color | **Well-grounded** (Gauge stops in TemplateBuilder; simpler slice of #5) |
+| 7 | `computed-number` | Number(s) / Select | compute a Number/Gauge from arithmetic over inputs | **Well-grounded** (`overall-risk-mitigation` = arithmetic diff of ratings in `replace_risk`) |
+| 8 | `person-plus-role` | People | reveal a role/detail field per attached person or role Select | **Plausible** (People field + config real; pairing force inferred) |
+| 9 | `cross-reference-with-detail` | CrossReference | on attach, reveal detail/linked fields; optionally pull linked values | **Well-grounded** (CrossReference 2nd most-used; `risk_mapping` attaches hazards/controls; `addLinkedFieldConfig`) |
+| 10 | `select-drives-tags` | Select / Checklist | chosen answer(s) add/remove page tags (register membership) | **Well-grounded** (`update_severity_force` NOTIFIABLE; `tag-on-level` in `replace_risk`; memory: register membership via tags) |
+| 11 | `signoff-block` | Signature (+ People + Date) | reveal/require signature block when a gate answer is set | **Plausible** (Signature field real; conditional-required is force-level, see constraint) |
+
+Grounding legend: **Well-grounded** = the field shapes AND the force/flow behaviour were seen in
+production ooze scripts or are directly emitted by `TemplateBuilder`. **Plausible** = field types
+are real and the pattern is idiomatic, but the exact force wiring was inferred, not observed.
+
+---
+
+## 1. `conditional-detail-select`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | The canonical "if you picked X, tell us more". A single-select gate whose non-default answer(s) reveal and (force-)require a detail field. The workhorse archetype. |
+| **Parent question type** | `Select` (single; `config.select.multiple = false`) |
+| **Dependent fields** | 1+ detail fields — typically `PlainText` (free text) or `RichText` (formatted), hidden by default. Role: capture the "more info". |
+| **Flow / force behaviour** | On chosen answer(s): `show(detail)` + (force-enforced) required. On other answers: `hide(detail)` + `clear(detail)`. Mirrors `replace_risk`'s `(do fld (hide) (clear))` idiom. |
+| **`when` (JSON-Logic)** | `{"in": [{"var": "parent.selected"}, ["Yes"]]}` → effects `[{show_field: detail}, {set_required: detail}]`; else `[{hide_field: detail}, {set_value: {field: detail, value: null}}]` |
+| **Parameters** | `parent_label`, `options[]`, `reveal_on[]` (subset of options), `detail_fields[] {label, type, required_when_shown}` |
+| **Compiles to** | `addField(Select)` + `addSelectFieldOption`×N + `editFieldConfiguration(select.multiple=false)`; `addField(PlainText/RichText)` per detail (hidden); one `addForce` + `addBinding` for parent and each detail. |
+| **Notes / open Qs** | Default hidden state: is "hidden until shown" a template attribute or purely force-driven? `editFieldConfiguration` has `hideView` (base key) — likely the static default; force flips it. Needs confirmation. |
+
+## 2. `yes-no-with-evidence`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | "Did X happen? If yes, attach proof." Compliance/audit checks that need a photo, file, or short note only on the affirmative branch. |
+| **Parent question type** | `Select` (Yes/No) or a single `Checklist` item |
+| **Dependent fields** | `File` and/or `ImageGallery` (evidence) + optional `PlainText` (note). Hidden by default. |
+| **Flow / force behaviour** | `answer == "Yes"` → `show(evidence)` + force-required (at least one attachment); `"No"` → `hide` + `clear`. |
+| **`when` (JSON-Logic)** | `{"==": [{"var": "parent.selected"}, "Yes"]}` → `[{show_field: evidence}, {set_required: evidence}]` |
+| **Parameters** | `parent_label`, `evidence_kind` (`file`\|`image`\|`both`), `note?` (bool), `required_when_shown` |
+| **Compiles to** | Select + 2 options; `addField(File)` / `addField(ImageGallery)` + optional `PlainText`; force with bindings. |
+| **Notes / open Qs** | Specialisation of #1 with fixed Yes/No parent and attachment detail. File/Image field read/write key asymmetry is a known gem bug (memory `model_input_converter_mapping`) but does not affect **template-build** authoring. |
+
+## 3. `checklist-with-followup`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | An inspection checklist where any item marked non-compliant ("No"/unchecked) must open a corrective-detail field for that item. |
+| **Parent question type** | `Checklist` (multi-item, each item = label + checked) |
+| **Dependent fields** | One follow-up field per item (usually `PlainText`), hidden until its item triggers. |
+| **Flow / force behaviour** | For each item: `item.checked == false` (or a "fail" state) → `show(followup_i)` + force-required; else `hide` + `clear`. Iterated in the force the way `replace_risk`'s `map` over unit lists does. |
+| **`when` (JSON-Logic)** | per item: `{"==": [{"var": "checklist.items.i.checked"}, false]}` → `[{show_field: followup_i}, {set_required: followup_i}]` |
+| **Parameters** | `checklist_label`, `items[] {label}`, `followup_type`, `fail_state` (`unchecked`\|`checked`) |
+| **Compiles to** | `addField(Checklist)` (items are the checklist's own config); N `addField(PlainText)`; one force binding all items + all follow-ups. |
+| **Notes / open Qs** | Checklist item ids are instance-assigned; force must bind by ref/label. Whether "N follow-ups + 1 force" or "N small forces" is cleaner is an open authoring choice. |
+
+## 4. `multi-select-fanout`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | A multi-select "which of these apply?" where **each** selected option turns on a dedicated section/field-group; unselected ones are disabled/cleared. |
+| **Parent question type** | `Select` (multiple; `config.select.multiple = true`) or `Checklist` |
+| **Dependent fields** | One **section** (or field cluster) per option — e.g. the `replace_risk` per-`category` units (`equ`, `haz`, `cvp`, `env`, `peo`), each with its own like/consequence/gauge/rating fields. |
+| **Flow / force behaviour** | Directly from `replace_risk`'s `update-unit`: `(active (=sel category kind))` → if active, evaluate/show the section; if not, `(map-1 disable isec rsec)` + `(map-1 clear ...)`. |
+| **`when` (JSON-Logic)** | per option: `{"in": ["equ", {"var": "parent.selected"}]}` → `[{show_section: sec_equ}]`; else `[{hide_section: sec_equ}, {set_value: {field: sec_equ.*, value: null}}]` |
+| **Parameters** | `parent_label`, `options[]`, `section_template` (fields each option's section contains), `multiple: true` |
+| **Compiles to** | Select(multiple) + options; per option a `addSection`+`addStageSection`+ its `addField`s; one force reading the parent and binding every fanned-out section. |
+| **Notes / open Qs** | This is the compositional heart of the risk template — #5 is usually **nested inside** each fanned-out section. Section-level show/hide is the effect that most needs adding to EPTIR's grammar (DESIGN_NOTE §5a). |
+
+## 5. `risk-matrix`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | Classic likelihood × consequence risk rating. Two selects feed a lookup matrix that computes a rating, maps it to a level + color, and tags the page by severity. The single richest observed archetype. |
+| **Parent question type** | Two `Select` fields — `likelihood` and `consequence` (each single-select, ordered options 0..N). |
+| **Dependent fields** | `Gauge` (rating value + colored bands), a level `Select` (Low/Med/High/Very — auto-selected, locked), optional hidden `Number` rating field. |
+| **Flow / force behaviour** | Straight from `replace_risk_case.rb`: `(risk-rating con lik)` indexes a hard-coded matrix; `(risk-level rating)` buckets it; `set-risk` does `(do gau (lock) (set n))`, `(do lev (lock) (clear) (select level) (set-color level))`; `tag-on-level` adds `INHERENT HIGH`/`RESIDUAL HIGH` tags. |
+| **`when` (JSON-Logic)** | Not a boolean gate — a **computed** effect: `{set_value: {field: gauge, value: {"matrix_lookup": [{"var": "likelihood.weight"}, {"var": "consequence.weight"}, <matrix>]}}}` + threshold→level + threshold→tag rules. |
+| **Parameters** | `likelihood_options[]`, `consequence_options[]`, `matrix[][]` (rating table), `level_bands[] {min, label, color, tag?}`, `gauge_max` |
+| **Compiles to** | 2× Select+options; `addField(Gauge)` + `addGaugeFieldStop` per band (threshold+color); level Select+options; `editFieldConfiguration(gauge.max)`; one force encoding the matrix + level LUT + tag rules, bound to all fields. |
+| **Notes / open Qs** | Real forces support **inherent vs residual** pairs and `min-rating-difference` "uncontrolled risk" logic (`uncontrolled` fn) — a richer parametrization than a single matrix. Draft models one matrix; flag the inherent/residual variant as a parameter to add. Matrix values are the archetype's key parameter. |
+
+## 6. `select-drives-gauge`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | A single categorical answer maps to a numeric score shown on a colored gauge (severity score, maturity level). The 1-dimensional slice of #5. |
+| **Parent question type** | `Select` (single) with weighted options. |
+| **Dependent fields** | `Gauge` (score + bands). |
+| **Flow / force behaviour** | `set(gauge, selected_option.weight)` + gauge stops color it; lock the gauge. Same `(do gau (lock) (set n))` idiom. |
+| **`when` (JSON-Logic)** | `{set_value: {field: gauge, value: {"var": "parent.selected.weight"}}}` |
+| **Parameters** | `parent_label`, `options[] {label, weight}`, `gauge_max`, `bands[] {threshold, color}` |
+| **Compiles to** | Select + weighted options (`addSelectFieldOption {label, weight}`); `addField(Gauge)` + `addGaugeFieldStop`s + `editFieldConfiguration(gauge.max)`; force binding select→gauge. |
+| **Notes / open Qs** | Option `weight` is a real `addSelectFieldOption` key — the natural carrier of the numeric mapping, so the force may just read the weight. Confirm gauge can be force-`set` from weight without an explicit LUT. |
+
+## 7. `computed-number`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | A read-only field whose value is arithmetic over other fields (totals, differences, days-between, cost = qty × rate). |
+| **Parent question type** | None (no gate) — inputs are Number/Date/Select fields; the archetype is the **output** + its formula. |
+| **Dependent fields** | Output `Number` or `Gauge` (locked, hidden-from-edit). |
+| **Flow / force behaviour** | Force computes and `set`s the output, then `(lock)`. Grounded in `replace_risk`'s `overall-risk-mitigation` = `(- max-irating max-rrating)` written via `(do overall-risk-mitigation (lock) (set maxs-difference))`. |
+| **`when` (JSON-Logic)** | `{set_value: {field: out, value: {"-": [{"var": "a"}, {"var": "b"}]}}}` (or `*`, `+`, date-diff op) |
+| **Parameters** | `inputs[]` (field refs), `formula` (arithmetic expr), `output_type` (`number`\|`gauge`) |
+| **Compiles to** | `addField(Number/Gauge)` (output); force reads inputs, computes, sets+locks output. |
+| **Notes / open Qs** | Formula grammar needs bounding (arithmetic + date-diff only?). Overlaps #5 — a risk matrix is a specialised computed value; keep separate because #7 is gate-free and formula-driven. |
+
+## 8. `person-plus-role`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | "Who was involved, and in what capacity" — a People field paired with a role/relationship qualifier per person (witness/injured/first-aider). |
+| **Parent question type** | `People` (single or multi) |
+| **Dependent fields** | A role `Select` (or `PlainText`) capturing the capacity; optionally revealed only once a person is attached. |
+| **Flow / force behaviour** | `people.count > 0` → `show(role)`; optional force-required. |
+| **`when` (JSON-Logic)** | `{">": [{"var": "people.count"}, 0]}` → `[{show_field: role}, {set_required: role}]` |
+| **Parameters** | `people_label`, `singular` (bool), `role_options[]` (or free text), `person_schema_id?` |
+| **Compiles to** | `addField(People)` + `editFieldConfiguration(people.singular/personSchemaId)`; role Select/PlainText; force binding people→role. |
+| **Notes / open Qs** | **Plausible, not observed** — People fields are heavily used (40 hits) but a per-person role force wasn't seen. Per-person (vs per-field) role capture may need a repeating/table structure rather than a single Select; flag for design. |
+
+## 9. `cross-reference-with-detail`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | Attach related records from another register (hazards, controls, assets, permits) and reveal/pull detail once attached. The register-linking backbone. |
+| **Parent question type** | `CrossReference` (to a target register) |
+| **Dependent fields** | Detail fields shown on attach; and/or **linked fields** that mirror values from the referenced page (`addLinkedFieldConfig`). |
+| **Flow / force behaviour** | On attach → `show(detail)`; linked fields auto-populate from the source via linked-field config (not a force). `risk_mapping_case.rb` attaches "Associated hazard" + "Attach controls" cross-refs by id. |
+| **`when` (JSON-Logic)** | `{">": [{"var": "xref.count"}, 0]}` → `[{show_field: detail}]`; linked-field pull is config, not `when`. |
+| **Parameters** | `xref_label`, `register_id`, `single_select_mode`, `display_fields[]`, `linked_fields[] {source_field_key}`, `detail_fields[]` |
+| **Compiles to** | `addField(CrossReference)` + `editFieldConfiguration(crossReference {registerId, singleSelectMode, displayFields, hideCreate, hideAttach})`; `addLinkedFieldConfig {sourceFieldKey, crossReferenceId}` per linked field; optional detail fields + force. |
+| **Notes / open Qs** | Two distinct mechanisms here: **linked fields** (declarative config, pull values) vs **forces** (reveal detail). CrossReference is the 2nd most-used type (66 hits) so this archetype is high-value. Register membership interplay via tags overlaps #10. |
+
+## 10. `select-drives-tags`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | Answering a question changes the page's **tags**, which drives register membership, visibility, and policy routing (notifiable events, high-risk escalation, moving a record between registers). |
+| **Parent question type** | `Select` (single/multi) or `Checklist` |
+| **Dependent fields** | None structural — the effect is on page tags. May pair with a hidden marker. |
+| **Flow / force behaviour** | Chosen answer → `add-tag`/`remove-tag`. Directly from `update_severity_force` (severity → `NOTIFIABLE`) and `replace_risk`'s `tag-on-level` (`(tag-off ...) (tag-on tag)`). |
+| **`when` (JSON-Logic)** | `{"in": [{"var": "severity.selected"}, ["major", "critical"]]}` → `[{add_tag: "NOTIFIABLE"}]`; else `[{remove_tag: "NOTIFIABLE"}]` |
+| **Parameters** | `parent_label`, `option_to_tags` (map answer → tag set), `mutually_exclusive` (bool — clear siblings first) |
+| **Compiles to** | Select/Checklist + options; force reads answer, adds/removes tags. No new fields. |
+| **Notes / open Qs** | `add_tag`/`remove_tag` ARE in EPTIR's existing closed effect set (DESIGN_NOTE §5a) — this archetype compiles cleanly **today**, unlike the show/hide ones. Tag→register-membership is a platform rule (memory `register_membership_via_tags`), so this archetype has real downstream reach. |
+
+## 11. `signoff-block`
+
+| Aspect | Spec |
+|---|---|
+| **Intent / when to use** | A review/approval gate: capture signature + approver + date, revealed/required once the record reaches an approvable state. |
+| **Parent question type** | `Signature` (with companion `People` approver + `Date`) — often gated by a prior Select ("Ready for sign-off?"). |
+| **Dependent fields** | `Signature`, `People` (approver), `Date` (signed-on). |
+| **Flow / force behaviour** | Gate answer set → `show`/force-require the block; before that, hidden. Note the platform also has native stage sign-off (`editRequiredSignOffs`) — the archetype is the **in-form** variant. |
+| **`when` (JSON-Logic)** | `{"==": [{"var": "gate.selected"}, "Ready"]}` → `[{show_field: signature}, {set_required: signature}, {show_field: approver}, {show_field: date}]` |
+| **Parameters** | `gate_label?`, `require_approver` (bool), `require_date` (bool) |
+| **Compiles to** | Optional gate Select; `addField(Signature)` + `addField(People)` + `addField(Date)`; force binding gate→block. |
+| **Notes / open Qs** | **Plausible, not observed** in ooze scripts. Overlaps with native stage sign-off (`editRequiredSignOffs`, `editRequiredSignOffs` command) and workflow task sign-off — decide whether "sign-off" belongs at the **field/force** layer or the **stage/task** layer. Likely the latter for true approvals; keep this archetype for lightweight in-form acknowledgement. |
+
+---
+
+## Cross-cutting notes
+
+- **`required` is force-only.** Repeated because it shapes every reveal archetype: the template
+  cannot carry a `required` flag through the command bus, so "required when shown" is always the
+  force refusing submission / flagging the field. If the future Workflow Builder conditional-field
+  feature (in development, `10_forces_workflow_builder.md`) lands a native conditional-required,
+  these archetypes should retarget it and drop the hand-authored force.
+- **Effect grammar gap.** Of the effects these archetypes need — `show_field`, `hide_field`,
+  `show_section`, `hide_section`, `set_required`, `set_value`, `add_tag`, `remove_tag` — only
+  `set_value`/`add_tag`/`remove_tag` are in EPTIR's current closed set. #1–#9 and #11 depend on
+  adding the show/hide/require effects (DESIGN_NOTE §5a). #10 compiles today.
+- **Reverse-classification is blocked.** Clustering the ~300 existing templates back into these
+  archetypes needs reading forces off a page, which is the one blocked path
+  (`Query::PageWithForces`, DESIGN_NOTE §6). This catalog is therefore an **authoring-first**
+  taxonomy; treat archetype detection from existing forces as future work.
+- **Section vs field ownership.** #4 (fanout) and #11 (block) reveal whole **sections**;
+  #1/#2/#3/#8 reveal individual **fields**. The macro needs to know which it owns so it can emit
+  `addSection`/`addStageSection` vs plain `addField` and bind the force at the right granularity.
+
+## Patterns seen repeatedly in real ooze scripts
+
+- **Weighted single-selects feeding computed risk** is the dominant real pattern (`replace_risk`,
+  `update_severity_force`): likelihood/consequence selects → matrix → gauge + level + color + tags.
+- **`(do <field> (lock) (clear) (select ...) / (set ...) (deindex-empty) (hide))`** is the universal
+  force idiom for computed/reveal fields — lock, clear, write, (optionally) hide, and drop empties
+  from the index. Every archetype's expansion should assume outputs are locked.
+- **Tags as the escalation/routing mechanism** (`NOTIFIABLE`, `INHERENT HIGH`) appears in both
+  incident and risk templates — #10 is genuinely load-bearing, not decorative.
+- **Cross-reference attach + per-answer section enable/disable** (`risk_mapping`, `replace_risk`
+  per-`category` units) confirms #4 and #9 as real composite shapes, not just single fields.

data/.ai-assistance/projects/template-model-logic/CLASSIFICATION_SPIKE.md

@@ -0,0 +1,243 @@
+# Spike — Reverse-Classifying Existing Template Questions into Archetypes
+
+> **Question.** Can we read the ~300 existing templates' questions and cluster them back into
+> "categories/archetypes" — where an archetype = *parent question (Select/Checklist) + dependent
+> fields + the force(s) that reveal/require/compute them per answer*? What does that depend on?
+>
+> **Scope.** Feasibility + prerequisites only. No code changes. Companion to
+> `DESIGN_NOTE.md` (which frames the *authoring* direction); this spike is the *reverse* direction.
+> All code claims are cited `file:line` and verified against the current tree
+> (branch `feature/model-input-fixes`, 2026-07-07).
+
+---
+
+## 1. Feasibility verdict
+
+**Partially feasible today; fully feasible with one small, already-triaged query-shape fix.**
+
+- The **structural half** of an archetype (parent Select/Checklist + its options + adjacent
+  dependent fields, plus `genomeSignature` and `ref` as equivalence signals) is **readable now** —
+  the page/template read model and its fragments already fetch everything needed.
+- The **flow half** (which answer reveals/requires/computes which field) lives in **Forces**, and
+  **reading forces off a page is the one blocked path** — but the blocker is a *client-side
+  query-shape bug*, not a missing backend or a missing model. The Force model, bindings model,
+  read fragment, and read query all already exist in the gem; the query and fragment simply select
+  fields the schema rejects. The fix is enumerated to the line in `.ai-assistance/projects/TODO.md`.
+- Even once forces are readable, the **force `script` is an AngularJS/LISP string** with no
+  structured answer→effect representation available today. Extracting `answer == "Yes" → show(F)`
+  requires parsing that string. This is the **honest residual risk** and it does not go away with
+  the query fix (see §5, §6).
+
+So: **structure-only classification is unblocked and gives a useful first pass; authoritative
+classification (with the flow contract) needs (a) the forces-read fix — cheap — and (b) a force
+script parser — the real work.**
+
+---
+
+## 2. Per-signal reliability assessment
+
+Ranked by authoritativeness for identifying an archetype.
+
+### 2.1 Force bindings + script — AUTHORITATIVE, but gated + needs parsing
+
+A `Force` connects fields/sections via **bindings** and encodes the show/hide/require/compute logic
+in its `script`. This is the *only* signal that actually tells you the flow contract.
+
+- **Model exists.** `Base::Force` exposes `id`, `name`, `script`, `customScript`, `weight`, `url`,
+  `globalBindingIds`, and `bindings` — `lib/ecoportal/api/graphql/base/force.rb:19-28`.
+- **Bindings expose the field/section link.** `Base::Force::Binding` carries `name` + `referenceId`
+  (the bound field/section id) — `lib/ecoportal/api/graphql/base/force/binding.rb:7-14`. The
+  collection can look up by name — `.../binding_collection.rb:19-22`.
+- **The page model surfaces forces** — `Interface::BasePage#forces` wraps `doc['forces']` in a
+  `Force::Collection`, and the page carries a `hasForces` boolean —
+  `lib/ecoportal/api/graphql/interface/base_page.rb:75-83`.
+- **A read fragment + read query exist.** `Fragment::ForceFields` selects
+  `id name script customScript globalBindingIds bindings{...}` —
+  `lib/ecoportal/api/graphql/fragment/force.rb:6-26`. `Query::PageWithForces` fetches
+  `page { ...PageFields; forces { ...ForceFields } }` —
+  `lib/ecoportal/api/graphql/query/page_with_forces.rb:31-38`.
+
+**Reliability caveats even once readable:**
+- `bindings` give you *which* fields a force touches (the cluster membership) — high value, structured.
+- The `script` gives you the *per-answer effect* — but only as an unparsed AngularJS/LISP string
+  (`script` / `customScript` are opaque text). No structured answer→effect map is exposed. See §5.
+- A force applies to a stage only if *all* its bindings resolve in that stage
+  (`10_forces_workflow_builder.md:16-21`), so binding→field resolution must be done per stage.
+
+### 2.2 Field structure / adjacency — AVAILABLE NOW, heuristic only
+
+"A Select followed by N fields in the same section" is readable directly from the page/template read
+model: stages → sections → fields.
+
+- Sections and their fields are fetched by the page fragment —
+  `lib/ecoportal/api/graphql/fragment/pages/common_page_union.rb:105-131` (`sectionUnion` →
+  `ContentSection.dataFields` / `SplitSection.left/rightDataFields`).
+- The gem exposes stage→section→field traversal (`page.stages`, `section.components`,
+  `get_by_type`, `get_by_name`) — documented in `07_data_fields.md:152-168`.
+- 20+ concrete field types are dispatched via `Base::Page::DataField::TYPE_MAP`
+  (`07_data_fields.md:19-45`); `Select`/`Checklist` parents are identifiable by `__typename`.
+
+**Reliability: heuristic.** Adjacency correlates with, but does not prove, a conditional
+relationship. A detail field can sit adjacent to its parent for layout reasons with no force, or a
+force can reveal a field in a *different* section. Adjacency gives you *candidate* clusters to then
+confirm against forces. On its own it will both over-group (adjacent-but-independent fields) and
+miss (force reveals a distant field). **Usable for a first-pass bucketing; fragile as ground truth.**
+
+### 2.3 genomeSignature — STRONG-BUT-FALLIBLE equivalence signal (not a clustering signal)
+
+- **Fetched today.** The data-field fragment selects `genomeSignature`
+  (`fragment/pages/common_page_union.rb:124`) and the model reads it —
+  `lib/ecoportal/api/graphql/base/page/data_field.rb:45` (`passthrough :label, :deindex, :genomeSignature`).
+- **Already consumed as a pairing signal.** The diff pairing engine uses it, weighted highest
+  (0.5) but explicitly not ground truth — `lib/ecoportal/api/graphql/diff/pairing/signals.rb:24-35`
+  and `WEIGHTS` at `:17-22`. The header documents 6 known failure modes
+  (`signals.rb:6-12`).
+
+**Role for classification: equivalence, not clustering.** genomeSignature tells you *"this field in
+template A is the same field as that field in template B"* — invaluable for saying *"the same
+archetype instance recurs across N templates"* once you've identified it once. It does **not** tell
+you *which fields form a cluster within one template* (that's bindings/adjacency). Treat it as the
+cross-template dedup / recurrence signal, not the intra-template grouping signal. Fallible: reused/
+re-purposed fields keep a stale genome, and newer field types may lack one (`signals.rb:8-12,31`).
+
+### 2.4 Select option sets, labels/descriptions, `ref` — SUPPORTING signals
+
+- **Option sets** — the parent's option labels/ids are read as part of the field data
+  (`Select` typed field; `07_data_fields.md:59`). Useful to name the archetype (e.g. a Yes/No
+  reveal) and to map `reveal_on` answers once the script is parsed.
+- **Labels/descriptions** — `label` is fetched (`common_page_union.rb:123`). The DESIGN_NOTE notes
+  the platform's identity trick is a hidden section-marker field + field `description` as keys
+  (`DESIGN_NOTE.md:96-98`) — so `description` doubles as an authored archetype/section key when present.
+- **`ref`** — the ES index key, `<type>.<hash_of_label>` (`07_data_fields.md:181-197`). Stable-ish
+  per label; **breaks when the label changes** and can be per-instance if a field was script-added
+  without copying from template (`07_data_fields.md:194-197`). Weak identity aid, not a cluster key.
+
+---
+
+## 3. Is fixing the forces-read blocker a PREREQUISITE?
+
+**For authoritative reverse-classification (archetype WITH its flow contract): YES.**
+The flow half of an archetype is defined by forces (bindings + script). Bindings are the structured
+statement of *which fields move together*; without reading them you are guessing cluster membership
+from adjacency alone. There is no other exposed source of the conditional flow on the platform today
+(the Workflow Builder's conditional-field workflows that would replace forces are still *in
+development* — `10_forces_workflow_builder.md:83-96`, `86-88`).
+
+**For a structure-only first pass (adjacency + genome + options): NO.**
+You can bucket questions into *candidate* archetypes from the read model alone (§2.2–2.4) without any
+forces access. This is useful for triage and to size the problem, but it is **fragile** (see §2.2):
+it cannot distinguish "Select with a genuinely conditional follow-up" from "Select that happens to
+sit above an always-visible field," and it will miss cross-section reveals. Any number you report
+from adjacency-only is a *lower-confidence estimate*, not a classification.
+
+**Net:** the forces-read fix is a **prerequisite for the real deliverable** but **not** for an
+initial scoping pass. Given the fix is cheap (§4), there is little reason to ship the fragile
+version as anything more than a scoping estimate.
+
+---
+
+## 4. Minimal-unblock sketch (forces read)
+
+The blocker is a **client query-shape bug**, fully triaged in `.ai-assistance/projects/TODO.md:14-24`
+(verified there against the live schema on 2026-07-03 — "all THREE are REAL bugs"). Two edits:
+
+1. **`Query::PageWithForces` selects `forces` directly on a union.** The query hangs `forces` off
+   the `PageUnion`, which is invalid GraphQL (can't select a field on a bare union) —
+   `query/page_with_forces.rb:33-35` (`forces { spread :ForceFields }`). **Fix:** wrap in the shared
+   interface — `... on BasePageInterface { forces { ...ForceFields } }` (per TODO.md:16-17).
+
+2. **`Fragment::ForceFields` selects `id` on binding types that have none.** The fragment selects
+   `id` inside `... on DataFieldBinding` and `... on SectionBinding`
+   (`fragment/force.rb:14-23`), but those types expose only `name`/`referenceId` (no `id`) —
+   `TODO.md:16-17`. **Fix:** drop `id` from the binding selections (keep `name`, `referenceId`).
+   Note `Base::Force::Binding` declares `passkey :id` (`base/force/binding.rb:8`) — harmless once the
+   query stops requesting it, since the model tolerates a missing key.
+
+3. **(eco-helpers, sibling repo — not this gem)** Split the capability gate.
+   `OozeRedirect.force_support?` hard-returns `false`, which gates **read and write together**, so
+   the broken read disables the working write as collateral — `10_forces_workflow_builder.md:50-54`,
+   RCA `.../analysis/2026-07-01-forces-via-workflow-commands-miss-rca.md:28-36,59-70`. For
+   *reverse-classification* we only need the **read** path, so this repo's job is items 1–2; the
+   eco-helpers gate split matters for the ooze scripts, not for a classifier that calls
+   `Query::PageWithForces` directly.
+
+**Verification step (not code):** these three queries have no render/validation specs; the same TODO
+item asks to add a render + schema-validation spec alongside the fix and to wire
+`tests/validate_queries.rb` into CI (`TODO.md:5-24`). Do that first so the fix is provably
+schema-valid against a fresh introspected schema before relying on it against 300 templates.
+
+**Effort:** two one-line selection edits + specs. Small. The model/fragment/query scaffolding is all
+already present (shipped as WIP alongside the write path in v1.3.11 per `CHANGELOG.md:184`).
+
+---
+
+## 5. Parsing the force script — the real difficulty
+
+Reading forces gets you the **bindings** (structured: which fields) and the **script** (unstructured:
+what happens per answer). The archetype's *per-answer effect* — `reveal_on: "Yes" → show + require`
+in the DESIGN_NOTE worked example (`DESIGN_NOTE.md:44-56`) — lives **only in the script string**.
+
+- `script`/`customScript` are opaque text (`base/force.rb:20`); the gem treats them as strings it
+  round-trips, never parses (write path just sets `customScript` and queues `editForce` —
+  `base/force.rb:33-38,55-60`). There is **no structured effect representation** exposed anywhere.
+- The scripts are **AngularJS/LISP snippets** (`10_forces_workflow_builder.md:9`,
+  `base/force.rb:6`). Extracting a reliable `answer → {show|hide|require|compute}(field)` mapping
+  from arbitrary such snippets is an **interpreter/parser problem**, with a long tail of hand-written
+  variants across 300 templates and 10+ orgs (~22 force-dependent ooze cases catalogued —
+  RCA `:27`). Expect: bespoke idioms, computed risk-matrix math, multi-condition guards, indirection
+  through global bindings (`globalBindingIds` — `base/force.rb:22`).
+- The **bindings alone** are a meaningful partial win: they tell you the *cluster membership* (this
+  force ties this Select to these N fields/sections) with high confidence, even if you never parse
+  the script. That yields "these fields form a conditional cluster governed by force X" — enough to
+  identify *that* an archetype exists and its members, if not its exact per-answer semantics.
+
+**Structured alternative:** the **Workflow Builder** conditional-field workflows are the intended
+structured replacement for force scripts — but they are **in development, not deployed**
+(`10_forces_workflow_builder.md:83-96`) and the API is explicitly "not stable enough for scripting
+against its internals" (`:98-104`). So there is **no structured flow representation available today**
+for existing templates; existing conditional logic is in AngularJS forces. Reverse-classification of
+the *installed base* cannot wait for Workflow Builder without leaving the ~300 current templates
+uncovered.
+
+---
+
+## 6. Open risks (honest)
+
+1. **AngularJS script parsing (highest).** No structured effect map exists; extracting
+   answer→effect from arbitrary LISP/AngularJS snippets across 300 templates is the dominant unknown.
+   Mitigate by (a) classifying on **bindings + adjacency + options** first (cluster membership +
+   candidate parent), and (b) parsing scripts only for a **closed catalog** of common idioms,
+   flagging the long tail as "custom force — unclassified" rather than mis-parsing. This mirrors the
+   DESIGN_NOTE's closed-catalog recommendation (`DESIGN_NOTE.md:126-130`).
+2. **Forces-read fix unproven against a live org.** The fix is triaged from schema introspection but
+   the query has never run green against a force-bearing page (it shipped as WIP —
+   `TODO.md:24`, RISKS `.../ooze-graphql-native-migration/RISKS.md:19-30`). Live-test
+   `Query::PageWithForces` on a real force-bearing page before trusting bulk output.
+3. **Binding→field resolution is per-stage and can dangle.** A force shows only if all bindings
+   resolve in the stage (`10_forces_workflow_builder.md:16-21`); bindings referencing removed/renamed
+   fields will dangle. Classifier must tolerate unresolved `referenceId`s.
+4. **genomeSignature fallibility for recurrence.** Re-purposed fields keep a stale genome and newer
+   types may lack one (`signals.rb:8-12,31`) — so "same archetype across templates" via genome will
+   have false matches/misses. Confirm with type+label+options (the existing pairing engine already
+   does exactly this weighting — `signals.rb:17-22`).
+5. **`ref` instability.** Label-hash based and per-instance when script-added
+   (`07_data_fields.md:194-197`) — do **not** use `ref` as a cluster or identity key; it is at best a
+   weak tiebreaker.
+6. **Forces are being deprecated mid-flight.** New templates use Workflow Builder, old ones use
+   forces (`10_forces_workflow_builder.md:61-65`). A classifier built purely on force-reading will
+   have blind spots on newer Workflow-Builder templates once conditional workflows deploy — plan for
+   a second reader against `PagesWorkflow` when that API stabilises.
+
+---
+
+## 7. Bottom line
+
+- **Structure-only classification:** doable now, no gem change — but a fragile first-pass estimate.
+- **Authoritative classification (with flow):** requires the **forces-read fix** (two one-line
+  selection edits in `Query::PageWithForces` / `Fragment::ForceFields`, already triaged in
+  `TODO.md:14-24`, plus a render/validation spec) — **cheap and low-risk**.
+- **The genuine hard part** is not the read fix; it is **parsing AngularJS force scripts** into
+  answer→effect mappings. Bindings give cluster membership cheaply; the per-answer semantics require
+  a parser, best scoped to a **closed catalog** of common idioms with a raw-force escape hatch.
+- **genomeSignature** is the cross-template recurrence signal (already wired in the diff pairing
+  engine), not the intra-template grouping signal.

data/.ai-assistance/projects/template-model-logic/DESIGN_NOTE.md

@@ -0,0 +1,154 @@
+# Design Note — A Template Model That Holds the Logic
+
+> For the team meeting. Goal: *"identify a template model that holds the logic — not just
+> questions and options, but the fields that get unhidden depending on the answer."*
+> Audience: engineers. Keep it skimmable.
+
+---
+
+## 1. The problem
+
+Our template representations today capture **structure** — stages, sections, fields, and (for
+Selects/Checklists) their options. What they do **not** capture is the **conditional flow**: the
+fact that answering a parent question a certain way reveals follow-up fields, makes them required,
+or computes a value. On the platform that flow lives in **Forces** (AngularJS snippets bound to a
+stage: show/hide sections/fields, conditional-required, computed values — being replaced by the
+Workflow Builder's "conditional field workflows", still in development). See
+`.ai-assistance/code/ecoPortal_architecture/10_forces_workflow_builder.md`. A template model that
+omits forces omits the actual behaviour of the form. This meeting is about giving the model a
+first-class place to hold that logic.
+
+---
+
+## 2. The category / composite question archetype
+
+**Reframe Oscar's "category" as a composite question archetype.** A category is not a field type —
+it is a **pattern one level above the flat field**:
+
+```
+archetype = parent question (usually Select / Checklist)
+          + its options
+          + the dependent fields it governs
+          + the force(s) that reveal / require / compute those fields per answer
+```
+
+The **category name** identifies the pattern; the category **carries the flow contract** — which
+answer unhides which fields, which answers flip a field to required, which answers drive a computed
+value. It is a **higher-order primitive above the flat field level**: a cluster of fields plus the
+force wiring that moves them together, referenced by name and parameters instead of spelled out.
+
+### Worked example — "conditional-detail Select"
+
+Author intent (one row / one macro):
+
+```
+category:      conditional_detail_select
+parent_label:  "Was anyone injured?"
+options:       ["No", "Yes"]
+reveal_on:     "Yes"
+detail_field:  { label: "Describe the injury", type: plainText, required_when_shown: true }
+```
+
+Expands to the flat model:
+
+- a `Select` field `Was anyone injured?` with options `No`, `Yes`
+- a `PlainText` field `Describe the injury`, hidden by default
+- a **force**: `when answer == "Yes"` → `show(detail_field)` + `set_required(detail_field)`
+
+One category, authored once, produces **two fields + one force with two effects**. Change the
+category and all of that regenerates coherently.
+
+---
+
+## 3. Where it sits in the pipeline
+
+The category is a **macro that expands into `fields + forces`** — it lives *above* the flat IR, not
+beside it. Layering:
+
+```
+requirements
+    ↓
+form design
+    ↓
+CATEGORIES  (composite archetypes: parent + options + dependents + forces)  ← the new layer
+    ↓  expand
+flat IR  (EPTIR: fields + tags + forces)                                    ← existing (parked)
+    ↓  compile
+ecoPortal implementation  (WorkflowCommandInput command-bus)                ← shipped
+```
+
+The flat IR already exists in draft as **EPTIR** (ecoPortal Template Intermediate Representation,
+parked in `C:\ruby_scripts\git\eptir`, v0.1 / `2026.1` DRAFT). The category layer does not replace
+EPTIR — it **compiles down into it**. `Builder::TemplateBuilder` + `Diff::CommandSynthesizer`
+already compile a flat declarative spec into `WorkflowCommandInput` batches, so the bottom two
+layers are real; categories add a compile step on top.
+
+---
+
+## 4. What it buys us
+
+- **Compresses the CSV pipeline.** The CSV→~300-templates work
+  (`.ai-assistance/projects/api-v2-to-graphql-migration/notes/csv-template-pipeline-design.md`,
+  delivery Sept 2026) today needs one row per field plus separate spelling-out of every dependent
+  field and force. A category row references `category + params` and expands to the whole cluster —
+  far fewer rows, far less force hand-authoring, mistakes localised to the macro.
+- **A natural pairing / identity anchor.** A category is a cluster of fields that move together, so
+  it is the obvious identity unit. It rides directly on the existing identity tricks — the
+  hidden section-marker field (section key) and field `description` (field key) — by anchoring the
+  whole cluster to one category key instead of tracking N loose fields + forces independently.
+- **A cleaner diff unit.** A change becomes *"this question's category changed"* or *"a category
+  parameter changed"* — one semantic delta — instead of a shower of add/remove field + add/edit
+  force/binding deltas. This is exactly the granularity the template diff-deploy work
+  (`.ai-assistance/projects/template-diff-deploy/`) wants.
+
+---
+
+## 5. The three decisions to nail in the meeting
+
+**(a) Grow the forces effect grammar.** EPTIR's forces are modelled as a JSON-Logic `when` plus a
+**closed effect set of `add_tag / remove_tag / set_value`**. That set does **not** include
+`show/hide field|section` or `set_required` — which is precisely the flow Oscar is describing. The
+category concept cannot expand into EPTIR until the effect grammar gains `show_field` / `hide_field`
+/ `show_section` / `hide_section` / `set_required` (all still closed, statically analysable). Decide
+this and it flows into the parked EPTIR spec.
+
+**(b) Which direction do we solve first — authoring or reverse-classification?** The same taxonomy
+serves two uses:
+- **Authoring** (design → categories → template): forward, and the write path is shipped
+  (`WorkflowAddForceInput`/`editForce`/`addBinding` via `executeWorkflowCommands`).
+- **Reverse-classification** (read ~300 existing templates → cluster field+force clusters back into
+  categories): depends on **reading forces off a page**, which is the **one blocked path**
+  (see §6).
+
+  Recommend committing to **authoring-first**: it is unblocked, it directly serves the Sept 2026
+  CSV delivery, and it lets us validate the taxonomy before we depend on the blocked read path.
+
+**(c) Closed catalog vs open user-defined archetypes.** A fixed catalog of ~N archetypes
+(conditional-detail Select, mutually-exclusive Checklist reveal, computed risk matrix, …) vs. an
+open, user-definable system. **Recommend closed-first** given the Sept 2026 deadline: a small closed
+catalog is faster to build, trivial to conformance-test, and covers the common cases; leave an
+escape hatch (raw fields+forces) for the long tail and revisit openness later.
+
+---
+
+## 6. The one concrete blocker
+
+**Reading forces off a page is blocked.** `Query::PageWithForces` (used by
+`ForceCompat#with_each_entry`) currently fails **client-side schema validation** (PageUnion
+selections, `id` on binding types) — `10_forces_workflow_builder.md` lines 46-54. **Writing** forces
+works today via the command bus. So authoring-first is fully unblocked; any reverse-classification of
+existing templates is gated on fixing this read query. Name it in the room so ownership is clear.
+
+---
+
+## 7. Recommendation
+
+1. Adopt the **composite question archetype ("category")** as a new layer that compiles down into
+   the flat fields+forces IR (EPTIR) — do not fold it into the flat layer.
+2. **Extend EPTIR's forces effect grammar** with `show/hide field|section` + `set_required`
+   (decision 5a) — this is the concrete spec change that unblocks everything else.
+3. Ship a **closed catalog** of a handful of archetypes (5c), **authoring-first** (5b), targeting the
+   CSV pipeline for Sept 2026.
+4. File **fixing `Query::PageWithForces`** as the tracked prerequisite for reverse-classification
+   (§6), but do not let it block the authoring track.
+```