ecoportal-api-graphql 1.3.10 → 1.3.12

data/.ai-assistance/skills/procedural-memory/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: procedural-memory
+category: governance
+version: 0.2.0
+status: draft
+description: >
+  Distills accumulated session signals into stored `procedural` memory entries
+  (recurring routines: a trigger condition + the action that reliably follows) and
+  surfaces them as likely next steps. Invoke on a periodic distill pass or when a
+  developer asks what patterns you have noticed in how they work.
+triggers:
+  - what patterns have you noticed
+  - distill my routines
+  - procedural memory
+  - how do I work
+  - learn my routines
+  - weekly distill
+  - modus operandi
+applicable_to:
+  - any
+---
+
+# procedural-memory
+
+## Purpose
+
+Turn the substrate of accumulated session history into stored **`procedural`** memory --
+recurring routines, each expressed as a **trigger condition** and the **inferred action**
+that reliably follows it -- and surface those routines (plus a short "likely next steps"
+list) so the next session starts proactively shaped instead of from scratch.
+
+This skill operationalizes the **Distill** stage of the Observe -> Distill -> Act loop, plus
+the human-facing part of the **Act** stage (surfacing). It implements
+`standards/workflows/procedural-memory.md`. Observation (the `Stop`/`SessionEnd` logging
+substrate) and autonomous execution (the auto-worker) are out of scope here -- this skill
+reads the Observe substrate and writes the inferred routines; it never acts on them itself.
+
+> **v0.2.0 -- draft-aligned, blockers resolved.** This skill tracks
+> `standards/workflows/procedural-memory.md` at v0.2.0 (`status: draft`, ready for consolidation
+> review). It implements the now-decided **decay/retirement lifecycle** (D1) and **Observe-stage
+> privacy policy** (D2). The distill cadence, the minimum-observation threshold, the promotion
+> rule, and the lifecycle numbers (confidence steps, retirement floor, staleness/cool-off
+> windows) are all **provisional** and will firm up when the standard reaches `status: reviewed`.
+> Treat the numbers below as conservative defaults, not settled policy.
+
+---
+
+## When to invoke
+
+- **On a periodic distill pass** -- e.g. weekly, or as part of an end-of-week wrap-up. This is
+  the primary mode: a scheduled mining pass over accumulated session history.
+- **On demand** -- when a developer asks "what patterns have you noticed in how I work?",
+  "distill my routines", or similar. Run the same procedure, scoped to the data available.
+
+Do not invoke this skill to *perform* a routine -- it only distils and surfaces. Acting on a
+surfaced routine is gated separately (see HARD CONSTRAINTS).
+
+---
+
+## On invocation
+
+Before any other output, do both of the following:
+
+1. Print to the user:
+   `[skill: procedural-memory] <one-line description of what you are about to do>`
+   Examples:
+   - Periodic pass: `[skill: procedural-memory] weekly distill — mining usage log for recurring routines`
+   - On demand: `[skill: procedural-memory] reviewing session history for patterns in how you work`
+
+2. Append a usage record to `.ai-assistance/local/kpi/usage-<YYYY-WNN>.jsonl`
+   (ISO week format, e.g. `2026-W26`):
+   ```json
+   {"component": "skill/procedural-memory", "action": "invoked", "detail": "<same one-liner>", "ts": "<ISO timestamp>", "session_id": "<if known>"}
+   ```
+   Before writing, run the scrub/redaction pass (see Privacy below) over the record. If the file
+   or directory does not exist, create it. If writing fails, continue silently.
+
+### Consent check (do this first)
+
+The Observe log is **opt-in**. Before reading any `usage-*.jsonl` to mine routines, confirm the
+developer has enabled Observe (`procedural_memory.observe: true` in local settings, or the
+equivalent Observe-hook entry). If consent is not set, report that the Observe stage is not
+enabled, do NOT read the log, and stop. (Writing this skill's own invoked/completed usage
+records is the skill announcing itself and is unaffected by the Observe consent flag.)
+
+---
+
+## The procedure
+
+### Step 1 -- Read the Observe substrate
+
+The Observe stage is append-only and machine-local; this skill only reads it. Read only after
+the consent check above has passed.
+
+- Read `.ai-assistance/local/kpi/usage-<YYYY-WNN>.jsonl` across the distill window (default: the
+  current and previous 3 ISO weeks). These records carry only low-sensitivity signal: command/
+  tool names (not arguments), file paths/types touched, components invoked, event types and
+  `action` values, and coarse durations/counts -- never full arguments, file contents, or
+  prompt/response text (see Privacy below). Parse defensively: skip malformed/corrupt JSON lines
+  rather than failing the whole pass.
+- Optionally read `docs/worklog.md` for `<!-- LEARNING: ... -->` markers. These are the
+  human-authored analogue of a `procedural` entry and may seed the distill pass
+  (`standards/workflows/session-handoff.md`).
+
+If no usage log exists, report that the Observe substrate is not yet populated and stop --
+there is nothing to distil. Do not invent routines from a single session.
+
+### Step 2 -- Mine for recurring patterns
+
+A pattern is a **trigger condition** plus the **action that reliably follows it** within the
+same or the next session. Look for:
+
+- An action that consistently follows a specific event (e.g. a code-spec regeneration that
+  follows every merge to `main`).
+- A consistent ordering of actions (e.g. tests -> lint -> commit).
+- A deferral that is consistently picked up at a predictable later point.
+
+**Minimum-observation threshold.** A pattern is only written if it was **observed in >= 3
+distinct sessions** in the window. This default is deliberately conservative to stop a one-off
+coincidence becoming a stored routine; the standard leaves the exact number open, so treat
+this as **provisional**. Below threshold: note it as a *candidate* in the report, but do not
+write a memory entry.
+
+### Step 3 -- Write each confirmed pattern as a `procedural` memory entry
+
+Write each pattern at or above threshold into the repo-scoped memory directory
+`~/.claude/projects/<project>/memory/` (auto memory -- repo-scoped and machine-local), as a
+memory entry of **type `procedural`**. The body carries **Trigger:** and **Inferred action:**
+lines, mirroring how `feedback` entries use **Why:** / **How to apply:**:
+
+```markdown
+## [Short routine name]
+
+**Trigger:** [the observed condition that recurs]
+**Inferred action:** [what the developer reliably does next]
+**Confidence:** 0.6
+**First-observed:** [YYYY-MM-DD]
+**Last-observed:** [YYYY-MM-DD]
+
+Observed in X of Y opportunities across N sessions (source: usage-<YYYY-WNN> ... usage-<YYYY-WNN>).
+```
+
+New entries start at **Confidence: 0.6** (provisional) -- above the retirement floor, below full
+trust, so a freshly inferred routine starts on probation. **First-observed** and **Last-observed**
+are both set to the current distill-pass date on first write. These three lines are required: they
+drive the decay/retirement lifecycle in Step 3b.
+
+Then add the index pointer line to `~/.claude/projects/<project>/memory/MEMORY.md`, matching
+the existing index style:
+
+```markdown
+- [Procedural: <short routine name>](<filename>.md) — <one-line trigger → action summary>
+```
+
+Mark the entry clearly as `procedural` so it stays distinguishable from `user`/`project`
+memory (see HARD CONSTRAINTS).
+
+### Step 3b -- Re-evaluate, decay, and retire existing routines
+
+On every distill pass, before reporting, walk each existing `procedural` entry and update its
+lifecycle metadata (standard D1). Honour forced markers first, then apply the arithmetic.
+
+1. **Forced markers (one-shot, applied first).** Scan `docs/worklog.md` and the memory files for:
+   - `<!-- RETIRE: <short routine name> -->` -- retire that routine immediately (see step 4
+     below), regardless of confidence or recency.
+   - `<!-- CONFIRM: <short routine name> -->` -- set its **Confidence** to `1.0` and refresh
+     **Last-observed** to today.
+   Record that the marker was applied so it is not re-applied on the next pass.
+
+2. **Re-evaluate against this window.** For each routine whose **Trigger** occurred at least once
+   in the window:
+   - trigger fired AND inferred action followed: refresh **Last-observed** to today and
+     **increment Confidence by +0.1**, capped at `1.0`;
+   - trigger fired but action did NOT follow: **decrement Confidence by -0.2** (contradiction
+     costs more than a single confirmation earns -- intentional asymmetry);
+   - trigger did not fire at all: leave Confidence unchanged; do NOT refresh Last-observed.
+
+3. **Retire** a routine when EITHER its **Confidence < 0.3** (floor) OR its **Last-observed** is
+   **older than 90 days** (staleness window). All thresholds provisional.
+
+4. **Archive on retirement -- never silent-delete.** Move the entry file to
+   `~/.claude/projects/<project>/memory/retired/`, appending the retirement date and reason
+   (`confidence floor` / `staleness` / `forced`). Remove its line from `MEMORY.md`. Keep a
+   tombstone (routine name + retirement date + reason). When mining (Step 2), if a re-detected
+   Trigger/Inferred-action pair matches a tombstone retired **within the last 30 days**
+   (cool-off, provisional), do NOT auto-write it -- surface it as a *candidate* for the developer
+   to re-confirm. After the cool-off it may be written fresh at the initial confidence.
+
+### Step 4 -- Promotion (propose only)
+
+A routine observed consistently **across multiple repos** is a candidate cross-project trait
+for user-global memory in `~/.claude/CLAUDE.md`. **Propose it -- do not auto-promote.** Present
+the candidate and the evidence; the developer decides. The exact promotion threshold is an
+open question in the standard and is provisional here.
+
+### Step 5 -- Act / surface
+
+Present the result to the developer:
+
+1. The distilled routines (newly written and pre-existing) for this repo.
+2. A short **"likely next steps"** list inferred from the current state and the routines.
+3. For routines whose inferred action is mechanically actionable, **PROPOSE** (never auto-add)
+   an `[auto]` tag so the auto-worker could pre-stage it -- subject to the developer confirming
+   the tag. The `[auto]` tag is the authorization boundary; eligibility rules in
+   `standards/tooling/auto-worker-eligibility.md` still apply, and this skill never tags
+   anything itself.
+
+After surfacing, append a completion usage record:
+```json
+{"component": "skill/procedural-memory", "action": "completed", "detail": "<N routines written, M candidates, K promotions proposed>", "ts": "<ISO timestamp>", "session_id": "<if known>"}
+```
+
+---
+
+## HARD CONSTRAINTS
+
+From `standards/workflows/procedural-memory.md` -- these are not optional:
+
+- **A `procedural` entry is an inference, not an asserted fact.** It must remain visibly
+  distinguishable from `user`/`project` memory (which record things the developer stated), so
+  a wrong inference can be retired without eroding trust in asserted facts.
+- **Suggest, never act.** A distilled routine may *suggest* a next step or an `[auto]` tag, but
+  it must not drive an autonomous action without a human-in-the-loop confirmation. Any routine
+  that would trigger an irreversible or shared-system action is subject to
+  `standards/workflows/hitl-gates.md` -- inference grants no authority to act.
+- **Observe logging is opt-in, scrubbed, and machine-local (standard D2).** The Observe hook is
+  off by default; do not read the usage log to mine routines unless consent is set (see Consent
+  check). Capture only the documented allow-list -- command/tool names, file paths/types, event
+  types, durations -- and NEVER full arguments, file contents, diffs, or prompt/response text.
+  Run the scrub/redaction pass (regex for tokens/keys, emails, obvious PII; replace with typed
+  placeholders; drop a record that cannot be confidently scrubbed) BEFORE writing any record.
+  Never copy the log off the machine, into a versioned file, or into a `procedural`/promoted
+  entry -- entries store only the distilled Trigger/Inferred-action plus aggregate evidence.
+- **Decay and retirement are mandatory (standard D1).** Every `procedural` entry carries
+  **Confidence**, **First-observed**, and **Last-observed**. Each pass re-evaluates them, retires
+  entries below the floor or past the staleness window, honours `<!-- RETIRE: -->` /
+  `<!-- CONFIRM: -->` markers, and archives (never silently deletes) retired entries with a
+  cool-off tombstone so a retired routine does not silently reappear.
+- **Repo-relative paths only** in any versioned output. Use `~/.claude/...` solely as the
+  canonical memory location, never a developer's absolute filesystem path.
+
+### Privacy -- what the Observe log captures, redacts, and where it lives
+
+- **Captured:** command/tool names; file paths/types touched (repo-relative); event types and
+  `action` values; coarse durations and counts; timestamps, ISO-week, session id.
+- **Never captured:** full command arguments; file contents or diffs; prompt/response text; the
+  literal text of corrections/redirects (only that one occurred, and its coarse type); secrets,
+  tokens, credentials, env values.
+- **Redaction:** scrub-before-write -- regex detectors for tokens/keys (high-entropy strings,
+  `sk-`/`ghp_`/AWS-style prefixes), emails, obvious PII; matches replaced with `<REDACTED:...>`;
+  unscrubabble records dropped.
+- **Storage/consent:** lives only at `.ai-assistance/local/kpi/usage-<YYYY-WNN>.jsonl`
+  (machine-local, gitignored, never committed). Enable via `procedural_memory.observe: true` in
+  local settings; disable by removing it; the developer may delete the log at any time.
+
+---
+
+## Example -- one mined pattern -> resulting `procedural` entry
+
+**Observed.** Over four ISO weeks the usage log shows that in 4 of 4 sessions ending with a
+merge to `main`, the same or next session regenerates code-specs and bumps the changelog
+before any new branch is opened. 4 sessions >= the threshold of 3, so it is written.
+
+Resulting file `~/.claude/projects/<project>/memory/procedural-merge-followup.md`:
+
+```markdown
+## Post-merge spec + changelog routine
+
+**Trigger:** a feature branch is merged to `main`.
+**Inferred action:** regenerate code-specs and bump the changelog before opening the next branch.
+**Confidence:** 0.6
+**First-observed:** 2026-06-28
+**Last-observed:** 2026-06-28
+
+Observed in 4 of 4 opportunities across 4 sessions (source: usage-2026-W22 ... usage-2026-W25).
+```
+
+On a later pass, if a merge to `main` is NOT followed by the spec+changelog action, Confidence
+drops by 0.2; sustained contradiction (or a `<!-- RETIRE: Post-merge spec + changelog routine -->`
+marker, or 90 days without observation) retires it to `memory/retired/`.
+
+Index line added to `MEMORY.md`:
+
+```markdown
+- [Procedural: Post-merge spec + changelog routine](procedural-merge-followup.md) — merge to main → regenerate code-specs + bump changelog
+```
+
+Surfaced at the next post-merge session as a likely next step, with a *proposal* (awaiting
+confirmation) to tag "regenerate code-specs `[auto]`".
+
+---
+
+## What this skill does NOT do
+
+- Does not run the Observe stage -- it reads the usage log; it does not write session signals.
+- Does not execute any routine, autonomously or otherwise -- surfacing only.
+- Does not add an `[auto]` tag -- it proposes; the developer confirms.
+- Does not auto-promote a routine to `~/.claude/CLAUDE.md` -- it proposes; the developer decides.
+- Does not write a routine below the minimum-observation threshold.
+- Does not read the Observe log without consent set (Observe is opt-in, off by default).
+- Does not write any record to the usage log without first running the scrub/redaction pass.
+- Does not capture command arguments, file contents, diffs, or prompt/response text.
+- Does not copy machine-local log contents into any versioned or promoted file.
+- Does not silently delete a retired routine -- it archives to `memory/retired/` with a tombstone.
+- Does not re-write a routine retired within the cool-off window -- it surfaces it as a candidate.
+- Does not modify `user`/`project`/`feedback`/`reference` memory entries -- it only adds and
+  maintains `procedural` entries.
+
+---
+
+## Version note
+
+v0.2.0 is aligned with `standards/workflows/procedural-memory.md` at v0.2.0 (`status: draft`,
+ready for consolidation review). It implements the now-decided decay/retirement lifecycle (D1)
+and Observe-stage privacy policy (D2). The distill cadence (weekly placeholder), the
+minimum-observation threshold (`>= 3 sessions`), the cross-repo promotion rule, and the lifecycle
+numbers (initial confidence 0.6, +0.1/-0.2 steps, 0.3 floor, 90-day staleness, 30-day cool-off)
+are all provisional. They will be revisited and firmed up when the standard reaches
+`status: reviewed`; this skill should be re-versioned to match.

data/.ai-assistance/standards-version.json

@@ -1,21 +1,22 @@
-{
-  "ep-ai-standards-version": "1.5.0",
-  "applied-at": "2026-06-13",
-  "project-type": [
-    "ruby"
-  ],
-  "deferred": [],
-  "installed-components": {
-    "skills/code-specs": "0.0.0",
-    "skills/ep-ai-manager": "2.1.0",
-    "skills/dep-graph": "0.0.0",
-    "skills/corporate-policies": "1.0.0",
-    "skills/ai-instructions": "0.0.0",
-    "skills/spec-generation": "0.0.0",
-    "skills/gemini-assist": "0.0.0",
-    "skills/ruby-scripting": "0.1.0",
-    "skills/refactor": "0.0.0",
-    "skills/project-cycle": "0.0.0",
-    "skills/graphql-schema-analysis": "0.0.0"
-  }
+{
+  "ep-ai-standards-version": "1.5.0",
+  "applied-at": "2026-06-13",
+  "project-type": [
+    "ruby"
+  ],
+  "deferred": [],
+  "installed-components": {
+    "skills/code-specs": "0.0.0",
+    "skills/ep-ai-manager": "2.1.0",
+    "skills/dep-graph": "0.0.0",
+    "skills/corporate-policies": "1.0.0",
+    "skills/ai-instructions": "0.0.0",
+    "skills/spec-generation": "0.0.0",
+    "skills/gemini-assist": "0.0.0",
+    "skills/ruby-scripting": "0.1.0",
+    "skills/refactor": "0.0.0",
+    "skills/project-cycle": "0.0.0",
+    "skills/graphql-schema-analysis": "0.0.0",
+    "skills/procedural-memory": "0.2.0"
+  }
 }

data/CHANGELOG.md

@@ -2,6 +2,125 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.3.12] - 2026-07-09
+
+Compat-layer correctness for register **field filters** + the native `SearchConf` field-filter DSL.
+**Backwards-compatible** — bug fixes (broken field filters returned 0 results) + additive methods;
+no public return type changed. (The `get_by_name`→collection contract change is intentionally **not**
+in this release — it is a breaking change parked on `feature/model-input-fixes` for a deliberate,
+signed-off future decision.)
+
+### Fixed
+
+- **`Compat::FilterTranslator`** now routes register **FIELD** filters to the backend-correct ES
+  operation (previously emitted the system-key operation → 0 results):
+  - Date FIELD (key `date.zXXXX`) → `range_date_filter` + `path: membranes.date` (system date keeps
+    `date_filter`).
+  - Select FIELD (key `select_str.zXXXX`) → `has_any_filter` / `doesnt_have_any_filter` +
+    `path: membranes.select_str` + `field_key: 'selected'` (system option key keeps
+    `one_of_filter`/`none_of_filter`).
+  - `exact_filter` no longer derives a `membranes.<type>` path for **system** keys
+    (`external_id`/`id`/`state`) — a spurious path produced term `membranes.external_id.external_id`
+    → 0 results (silent miss → dup-on-upsert). Register FIELD keys still get the nested path.
+  - Verified against the backend filter definitions; catalogued in
+    `.ai-assistance/code/filter_contract_matrix.md`.
+
+### Added
+
+- **`SearchConf` field-filter DSL:** `sc[:'date.zXXXX'].between/since/before` now emits
+  `range_date_filter` + `membranes.date` for register Date FIELDs; new `FieldRef#any_of` / `#none_of`
+  → `has_any_filter` / `doesnt_have_any_filter` (path + `field_key`) for register field value
+  membership (distinct from `one_of`, which ORs `exact_filter` for system keys).
+- **`get_by_id`** on `DataField::Collection` and `SectionCollection` (v2-compat find-by-id) — fixes
+  `NoMethodError` in consumers that resolve a field/section by id.
+
+## [1.3.11] - 2026-07-04
+
+Template automatic **build & maintenance** engine (backwards-compatible — a self-contained new
+`Diff` module + a build emitter; nothing existing changed). Validated **offline** (specs + fixtures +
+shapes checked against the live schema dump); the live UAT→PROD round trip is pending a sandbox org.
+
+### Added
+
+- **`genomeSignature`** fetched on every data-field type (added once to the `dataFieldInterface`
+  fragment, `@skip(if: $only_content)`) + `passthrough :genomeSignature` on `Base::Page::DataField` —
+  a strong-but-fallible field-pairing signal.
+- **`Diff::VersionDiff`** — two same-object (retained-id) template snapshots → an exact structural
+  changelog: added/removed/changed/moved for stages, sections, fields (label/type/section-move),
+  select options (label/weight), **gauge stops** (add/remove/threshold/color, matched by stop id), and
+  typed **`byType` field config** (conservative, only confirmed read↔input-key matches: Gauge `max`;
+  Select `dataType/multiple/flat/other/otherDesc`; Date `showTime/pastOnly/todayButton`).
+- **`Diff::Change`** — command-ready change (`op`/`kind`/`id`/`label`/`path`/`attribute`/`before`/
+  `after`/`parent_id`/`by_type`) with a human `#description`; `#to_h` is the stable interchange shape.
+- **`Diff::CommandSynthesizer`** — a `Change` set → an ordered `WorkflowCommand` batch (the replayable
+  "commit"): moves/renames/config, options, gauge stops, `editFieldConfiguration(byType:)`, with
+  **`placeholderId` threading** so dependent intra-batch creates reference not-yet-created nodes.
+  Genuinely ambiguous cases (field type change, moves without a target id) are left **UNSUPPORTED** —
+  never guessed.
+- **`Diff::Deploy`** — `from_versions(before, after, target_doc:)` / `from_cross_object(...)` produce
+  the ordered batch ready for `executeWorkflowCommands`; `#execute!` refuses to run while the honest
+  `unsupported` list is non-empty unless `allow_partial: true`; inert until an executor is passed.
+- **`Diff::IdResolver`** — indexes a target doc's stage names + section headings → ids for move
+  resolution; duplicate keys resolve to `nil` (never guesses).
+- **`Diff::Pairing::{Engine,Signals,Candidate,Ledger}`** — multi-signal equivalence matching for
+  cross-object templates (genome 0.5 + type 0.2 + label 0.2 + options-by-value 0.1, averaged over
+  applicable signals; greedy 1:1; auto-accept ≥0.85, ambiguous 0.5–0.85, unmatched <0.5; genome
+  mismatch scores 0 but does **not** veto). `Ledger` persists confirmed pairs (consulted first;
+  human corrections supersede).
+- **`Diff::Strategy`** — composable diff modalities: pairing (`:id`/`:genome`/`:type_label`/
+  `:assisted`) × scope (`:structural`/`:config_only`/`:data_migration`) × move-sensitivity × intent
+  (`:changelog`/`:deploy`/`:sync_readiness`). `.default` reproduces exact pre-existing behaviour.
+- **`Diff::CrossObjectDiff`** — diffs two templates with **no shared ids** by building the
+  id-correspondence map via `Pairing::Engine` (+ optional `Ledger`), then emitting the same `Change`
+  output that feeds `CommandSynthesizer`/`Deploy`. Ambiguous/unmatched held in `#unresolved` for a
+  human — never auto-paired.
+- **`Builder::TemplateBuilder`** — a declarative template spec (stages→sections→fields→options→
+  config→gauge-stops) → an ordered `WorkflowCommand` batch for `Builder::Template#create/update`,
+  using the **same `placeholderId` threading** as the diff synthesizer so build-from-scratch and
+  diff-deploy emit through one layer. Emits only verified input `VALID_KEYS`. A field's `description`
+  (e.g. a CSV/hidden-field identity token) is emitted as a follow-up `editFieldConfiguration(
+  dataFieldId:, description:)` — the correct schema seam, since `WorkflowAddFieldInput` has no
+  `description` key.
+- **Stage/section back-refs on added nodes** (`Diff::CommandSynthesizer`) — an added field's `addField`
+  now carries `sectionId` (`Change#parent_id`) + `stageId` (new `Change#owner_id`); an added section
+  emits a follow-up `addStageSection(stageId:, sectionId:)`. All threaded via `ref()` (parent
+  placeholder when created same-batch, else real id; omitted when unknown → historical behaviour
+  unchanged). `VersionDiff` records `parent_id`/`owner_id` on added field/section changes.
+
+### Fixed
+
+- **Fragment references migrated to the `spread :Name` registry convention.** The Action and
+  ContractorEntity **mutations** (`create`/`update`/`destroy`, `create`/`update`/`archive`) still used
+  the dead `___Const__Fragment` convention, which resolves a Ruby constant `Fragment::<Name>` that no
+  longer exists (fragments are a registry now) → `uninitialized constant … Fragment::… (NameError)` at
+  render time. Now `spread :Action` / `spread :ContractorEntity`, matching the already-migrated queries.
+  (The sibling breakage in eco-helpers' location-command optimizations is fixed in eco-helpers 3.2.17;
+  it crashed the live act-gov locations sync.)
+- **Kickstand workflow mutations — bare `DateTime` selection.** `Kickstand::{Start,Stop,Fail}Workflow`
+  selected `startedAt`/`stoppedAt`/`failedAt` bare → "Field must have selections". Now
+  `{ dateTime timeZone }` (same class as the 1.3.10 LocationStructure fix).
+- **`tests/validate_queries.rb` now renders MUTATIONS too** (was queries only) and **hard-fails on a
+  render error** (dead fragment / unresolved constant), not just a soft skip — the offline guard for
+  both classes above. It caught the 3 Kickstand bugs immediately.
+
+### Schema realities (verified against the live introspection dump)
+
+- **`required` cannot be set via the workflow command bus** — there is NO `required` input key anywhere
+  in the schema (not on `WorkflowAddFieldInput`, not on `WorkflowEditFieldConfigurationInput` or any of
+  its 12 byType sub-inputs). Callers must treat field-`required` as **read-only / out-of-band**
+  (ecoportal-qa `:skip`s `required`-readiness by design).
+
+### Dependencies
+
+- **Requires `ecoportal-api-v2 >= 3.3.3`** (was `>= 3.3.2`). 3.3.2 has a Ruby-3.x `TypeError` in the
+  `DoubleModel` cascade (`_cascaded_attributes_trace`) that crashes `as_update`/`DiffService` on any
+  model with nested attributes — fixed in v2 3.3.3. Raising the floor stops the broken v2 from
+  resolving on consumers.
+
+### Known gaps (tracked, not in this release)
+
+- Live characterization (UAT→PROD replay + verify) is pending a sandbox org + credentials.
+
 ## [1.3.10] - 2026-07-03
 
 Hotfix (backwards-compatible). Resolves a live failure on the Turners & Growers users sync.

data/CLAUDE.md

@@ -11,8 +11,17 @@ docs/worklog.md                          ← current state, blockers, open quest
 .ai-assistance/projects/<slug>/TODO.md   ← active project task list
 .ai-assistance/local/paths.json          ← local paths to sibling repos (gitignored — machine-specific)
 .ai-assistance/bridge/CLAUDE.md          ← bridge protocol: format, lifecycle, cross-repo requests
+.ai-assistance/code/ecoPortal_architecture/  ← VERIFIED PLATFORM KNOWLEDGE — how the platform behaves
+                                            (data model, API layers, page/stage workflows, fields, search).
+                                            Read 00_overview_and_index first, then the area file for the
+                                            task at hand, BEFORE implementing platform logic. See ADR-012.
 ```
 
+> Platform behaviour is documented in `ecoPortal_architecture/` for a reason: do not infer a
+> stage/workflow/field rule from code alone when a verified note exists. If you confirm a new
+> platform fact, add it to the relevant doc with its evidence (`file:line` or "confirmed by
+> &lt;user&gt; on &lt;date&gt;") in the same session -- that tree is the durable, shared home.
+
 ---
 
 ## Repository Role
@@ -95,6 +104,7 @@ the developer explicitly requests it for a specific commit.
 | `spec-generation` | `.ai-assistance/skills/spec-generation/SKILL.md` | Generate RSpec specs for backwards-compat |
 | `refactor` | `.ai-assistance/skills/refactor/SKILL.md` | Identify and log refactoring opportunities |
 | `project-cycle` | `.ai-assistance/skills/project-cycle/SKILL.md` | Project planning, TODOs, decisions |
+| `procedural-memory` | `.ai-assistance/skills/procedural-memory/SKILL.md` | Distill recurring work routines and surface likely next steps |
 
 ---
 

data/docs/self-docs/ARCHITECTURE.md

@@ -0,0 +1,88 @@
+---
+schema_version: "1.0"
+repo: "ecoportal-api-graphql"
+doc: architecture
+last_generated: "2026-07-06"
+source_head: "2abd6fc"
+review_status: draft
+---
+
+# Architecture -- ecoportal-api-graphql
+
+**Scope:** High-level structure only. Deep per-area detail lives in `.ai-assistance/code/`
+(`code-specs`); link to it rather than duplicating.
+
+## Top-level structure
+
+| Directory | Role |
+|---|---|
+| `lib/` | The gem source. `lib/ecoportal/api/graphql/` holds the layered client; `lib/ecoportal/api/common/graphql/` holds shared utilities (HTTP client, base model, helpers, patches). |
+| `spec/` | RSpec specs, mirroring the `lib/` structure. |
+| `tests/` | Manual integration test scripts (live-API characterization, not the RSpec suite). |
+| `bin/` | Development console / helper executables. |
+| `scripts/` | Token-offload and tooling scripts (see `scripts/CLAUDE.md`). |
+| `docs/` | Human docs, worklog, and this self-docs set. |
+| `.ai-assistance/` | AI agent resources: code-specs, project intent/TODOs, skills, bridge, conventions. |
+| `.claude/` | Claude Code settings and hooks for this repo. |
+
+## Key components
+
+Reused from `.ai-assistance/code/OVERVIEW.md` and `.ai-assistance/code/ecoPortal_architecture/`;
+not re-analysed here.
+
+- **Main class `Ecoportal::API::GraphQL`** (`lib/ecoportal/api/graphql.rb`) -- the public entry
+  point, instantiated with credentials (email, pass, org_id, host). Exposes builders and
+  convenience shortcuts per domain.
+- **`Common::GraphQL::Client`** (`lib/ecoportal/api/common/graphql/client.rb`) -- the HTTP layer,
+  extending `Graphlient::Client`. Handles auth (`AuthService`), org context, and timeouts;
+  `no_schema: true` is always passed, so schema introspection is disabled and queries are not
+  validated against a schema at build time.
+- **Layered namespace** under `Ecoportal::API::GraphQL::` (folder mirrors module exactly):
+  `Builder` (developer-facing facade per domain) -> `Query` / `Mutation` (operation definitions)
+  -> `Logic` (execution: base_query, base_model, payload, input, connection) -> `Fragment`
+  (fragment strings) -> `Model` (read-side response models), `Input` / `Payload` (write side) ->
+  `Base` (shared base classes), `Interface` (GraphQL interface types) -> `Common::GraphQL::Client`.
+- **`Compat::` layer** -- v2 compatibility shims (`Pages`, `Registers`, `StageView`,
+  `StageCollection`, etc.) that let `eco-helpers` treat `graphql` as a drop-in for the older `apiv2`
+  interface.
+- **`Diff::` and `Builder::TemplateBuilder`** -- the template build-and-maintenance engine
+  (self-version and cross-object diff, pairing engine + ledger, `Change`-to-`WorkflowCommand`
+  synthesis, unified BUILD emitter). This is where current development is concentrated.
+
+## How they fit
+
+A consumer instantiates `Ecoportal::API::GraphQL` with credentials, then calls a `Builder` for the
+domain it wants (page, template, action, contractor entity, location structure). The builder
+composes `Query`/`Mutation` operations, which the `Logic` layer executes through
+`Common::GraphQL::Client` over HTTP. Fragments are assembled at query build time
+(`BaseQuery#assemble_fragments` scans query strings for `...FragmentName` spreads). Responses parse
+into `Model` objects (read side); mutations take `Input` objects and return `Payload` objects
+(write side). The `Compat` layer re-exposes this so downstream `eco-helpers` scripts keep working
+unchanged.
+
+## Entry points
+
+- `require 'ecoportal/api-graphql'` loads `ecoportal-api-v2` (and transitively `ecoportal-api`),
+  the version file, `ecoportal/api/common.graphql`, then `ecoportal/api/graphql`.
+- Runtime entry is `Ecoportal::API::GraphQL.new(email:, pass:, org_id:, host:)`.
+
+## Build / test tooling
+
+- Build: RubyGems / Bundler. Gem spec: `ecoportal-api-graphql.gemspec`. Version constant:
+  `Ecoportal::API::GRAPQL_VERSION`.
+- Tests: RSpec (`bundle exec rspec`). Live AI tests are `--tag live` and require `ANTHROPIC_API_KEY`
+  loaded from `.env` via `dotenv`.
+- CI: no CI config file was detected at the repo root by the scanner (`ci_files: []`).
+  <!-- TODO(human): confirm whether CI runs elsewhere (e.g. GitLab CI defined outside root) or is absent. -->
+
+## Links to detailed docs
+
+- `.ai-assistance/code/OVERVIEW.md` -- gem overview, entry points, namespace convention.
+- `.ai-assistance/code/ecoPortal_architecture/00_overview_and_index.md` -- verified platform
+  knowledge index (data model, API layers, page/stage workflows, fields, search).
+- `.ai-assistance/code/ecoPortal_architecture/11_integration_gems.md` -- the integration gem stack.
+- `.ai-assistance/code/dependencies.md` -- full dependency map (remotes, fork relationships).
+- `.ai-assistance/code/diff_pairing_engine.md`, `.ai-assistance/code/diff_service_deep_dive.md`,
+  `.ai-assistance/code/template_diff_pairing_domain.md` -- the template diff/build engine.
+- `.ai-assistance/code/data_fields.md`, `.ai-assistance/code/graphql_domain_knowledge.md`,
+  `.ai-assistance/code/schema_analysis.md` -- data-field and schema detail.

data/docs/self-docs/CHANGES.jsonl

@@ -0,0 +1,7 @@
+{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/OVERVIEW.md", "change": "created", "from_hash": null, "to_hash": "a43c976a85ebfad6"}
+{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/ARCHITECTURE.md", "change": "created", "from_hash": null, "to_hash": "b0989977a912aab1"}
+{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/CONVENTIONS.md", "change": "created", "from_hash": null, "to_hash": "1649159eb799a7b8"}
+{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/INTEGRATIONS.md", "change": "created", "from_hash": null, "to_hash": "bae9f91748e33af1"}
+{"ts": "2026-07-06T11:14:43Z", "file": "docs/self-docs/STATUS.md", "change": "created", "from_hash": null, "to_hash": "08841d1d45eea2d6"}
+{"ts": "2026-07-06T11:15:00Z", "file": "docs/self-docs/OVERVIEW.md", "change": "updated", "from_hash": "a43c976a85ebfad6", "to_hash": "391055c9a6a687b9"}
+{"ts": "2026-07-06T11:15:00Z", "file": "docs/self-docs/ARCHITECTURE.md", "change": "updated", "from_hash": "b0989977a912aab1", "to_hash": "ad05f25b95b49c00"}