ecoportal-api-graphql 1.3.12 → 1.3.13

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.
+```

data/.ai-assistance/scripts/bridge-inbox-check.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# bridge-inbox-check.sh -- session-start actuator for the bridge inbox.
+#
+# Closes an actuation-coverage gap: unread cross-project bridge messages used to be
+# visible only if someone manually ran a command. This is the trigger/clock that
+# surfaces them automatically at session start, mirroring the standards-inbox report
+# line (see CLAUDE.md and standards/governance/standards-request-protocol.md).
+#
+# DETERMINISTIC and zero-LLM: it just scans .ai-assistance/bridge/inbox/ for unread
+# messages (STATUS: PENDING) and prints one summary line plus one line per message:
+#
+#   [bridge] N unread message(s)
+#   - {title} from {FROM}
+#
+# Contract (mirrors the other hook scripts):
+#   - Silent (no output) and exit 0 when the inbox is empty or has no unread messages.
+#   - NEVER fails fatally -- always exits 0, even on a malformed file or missing dir.
+#   - No side effects: read-only, does not touch or move any message.
+#
+# Wired as a SessionStart hook in .claude/settings.json:
+#   bash scripts/bridge-inbox-check.sh 2>/dev/null || true
+#
+# Manual run (same output): bash scripts/bridge-inbox-check.sh
+set -u
+
+# Resolve the bridge inbox from this script's location so it works from any cwd.
+# This script is deployed at .ai-assistance/scripts/, so the inbox is a sibling
+# of the scripts dir: ../bridge/inbox (mirrors bridge-init.sh in this repo).
+SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)" || exit 0
+INBOX="$SCRIPT_DIR/../bridge/inbox"
+
+# No inbox -> nothing to report.
+[ -d "$INBOX" ] || exit 0
+
+# An "unread" message is a *.md file whose header carries STATUS: PENDING.
+# (PENDING = not yet picked up by the receiving agent; IN_PROGRESS/DONE/FAILED are read.)
+unread=""
+count=0
+
+for f in "$INBOX"/*.md; do
+  # Guard against the literal glob when the folder is empty.
+  [ -e "$f" ] || continue
+
+  # Only inspect the header block (first ~15 lines) -- cheap and format-stable.
+  header="$(head -n 15 "$f" 2>/dev/null || true)"
+
+  # Unread == STATUS: PENDING (case-insensitive, tolerant of surrounding whitespace).
+  printf '%s\n' "$header" | grep -Eiq '^[[:space:]]*STATUS:[[:space:]]*PENDING[[:space:]]*$' || continue
+
+  # Title: the text after "# TASK:" on line 1; fall back to the filename.
+  title="$(printf '%s\n' "$header" \
+    | grep -Ei '^#[[:space:]]*TASK:' \
+    | head -n 1 \
+    | sed -E 's/^#[[:space:]]*TASK:[[:space:]]*//' 2>/dev/null || true)"
+  [ -n "$title" ] || title="$(basename "$f" .md)"
+
+  # Sender: the text after "FROM:"; fall back to "unknown".
+  from="$(printf '%s\n' "$header" \
+    | grep -Ei '^[[:space:]]*FROM:' \
+    | head -n 1 \
+    | sed -E 's/^[[:space:]]*FROM:[[:space:]]*//I' 2>/dev/null || true)"
+  [ -n "$from" ] || from="unknown"
+
+  count=$((count + 1))
+  unread="${unread}- ${title} from ${from}
+"
+done
+
+# Silent when there is nothing unread.
+[ "$count" -gt 0 ] || exit 0
+
+printf '[bridge] %d unread message(s)\n' "$count"
+printf '%s' "$unread"
+
+exit 0

data/.ai-assistance/skills/project-self-docs/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: project-self-docs
+category: knowledge
+version: 0.2.0
+description: >
+  Generate and maintain a project's own committed self-documentation set (a stable-schema
+  OVERVIEW/ARCHITECTURE/CONVENTIONS/INTEGRATIONS/STATUS/COMPLIANCE/OPERATIONS) plus a machine-readable index and
+  changelog, so the project can later feed a central coordination hub. A thin orchestrator:
+  it reuses ai-discovery/code-specs/discovery-manifest findings and a deterministic scanner,
+  and never invents a documentation format. Invoke to create, refresh, or verify self-docs.
+triggers:
+  - self docs
+  - self-documenting
+  - project-self-docs
+  - generate project docs
+  - refresh self docs
+  - self document this project
+  - hub docs
+applicable_to:
+  - any
+---
+
+# project-self-docs
+
+## Role
+
+You maintain a project's SELF-DOCUMENTATION set: a small, stable set of committed markdown docs
+that describe what the project is and how it is built, plus a machine-readable index and changelog
+that a central coordination hub can consume. You are a THIN ORCHESTRATOR -- you compose facts that
+`ai-discovery`, `code-specs`, and the deterministic scanner already produce; you do NOT re-analyse
+the codebase from scratch, and you do NOT invent a new documentation format. Everything you write
+is idempotent and re-runnable: running twice on an unchanged repo changes nothing.
+
+This capability is the per-project half of the synergy hub (ADR-015, Section 8; and ADR-014). It exists
+to detune the fleet by making reuse possible -- a project that documents itself against a shared
+schema is a project others can find and build on instead of duplicating.
+
+---
+
+## On invocation
+
+Before any other output, do both of the following:
+
+1. Print to the user:
+   `[skill: project-self-docs] <one-line description of what you are about to do>`
+   For example:
+   - `[skill: project-self-docs] scanning repo and reporting self-doc status`
+   - `[skill: project-self-docs] refreshing STATUS.md and ARCHITECTURE.md from current state`
+   - `[skill: project-self-docs] creating the self-doc set for the first time`
+
+2. Append a usage record to `.ai-assistance/local/kpi/usage-<YYYY-WNN>.jsonl`
+   (ISO week format: `YYYY-WNN`, e.g. `2026-W24`):
+   ```json
+   {"component": "skill/project-self-docs", "action": "invoked", "detail": "<same one-liner>", "ts": "<ISO timestamp>", "session_id": "<if known from token-budget session>"}
+   ```
+   Use `action` values: `invoked`, `completed`, `skipped`. If the file or directory does not
+   exist, create it. If writing fails, continue silently.
+
+---
+
+## Before answering -- run the deterministic scan FIRST
+
+The deterministic scanner does the zero-LLM half. ALWAYS run it before writing any prose, so you
+spend interactive tokens only on the semantic gaps it cannot fill:
+
+```bash
+python .ai-assistance/skills/project-self-docs/scripts/self_docs_scan.py --json
+```
+
+(From ep-ai-standards itself, the script lives at
+`skills-library/project-self-docs/scripts/self_docs_scan.py`.)
+
+The observation tells you deterministically: repo type, real repo name (from the remote), git
+head/branch, top-level structure, key config + CI files, activity clusters (hot paths), which
+existing inputs you can REUSE (`ai-discovery` `repo-context.md`/`conventions.md`, `code-specs`
+under `.ai-assistance/code/`), and which self-docs already exist with their current content hash.
+
+**Reuse before you write.** If `repo-context.md`, `conventions.md`, or code-specs exist, compose
+the self-docs from them -- do not re-derive the same facts. If they do NOT exist, propose running
+`ai-discovery` (first-time) or `code-specs` (per-area) first, rather than duplicating their work
+here.
+
+---
+
+## The self-doc set (stable schema -- do not change filenames)
+
+Copy the templates from `templates/project-self-docs/` into the project's self-docs directory
+(default `docs/self-docs/`; configurable). The set is intentionally small and fixed:
+
+| File | Covers |
+|---|---|
+| `OVERVIEW.md` | What the project is, who it serves, current priority (one screen) |
+| `ARCHITECTURE.md` | Top-level structure, key components, how they fit, entry points |
+| `CONVENTIONS.md` | Coding style, branch naming, commit style, test conventions |
+| `INTEGRATIONS.md` | External services + data + permissions, upstream/downstream repos, dependencies |
+| `STATUS.md` | Active work, migration state, known risks, open questions |
+| `COMPLIANCE.md` | ISO-27001/audit, data classes + PII, third-party vendors, AI content, leak controls |
+| `OPERATIONS.md` | Infrastructure, public exposure + Cloudflare, DevOps audit runbook, usage KPIs/ROI |
+
+The set is the ROVO audit/compliance/discovery surface once mirrored into the EP Projects Register
+(`docs/strategy/self-docs-audit-schema.md`). Schema is `1.1`. Each file carries YAML frontmatter
+(`schema_version`, `repo`, `doc`, `last_generated`,
+`source_head`, `review_status`) so the hub can parse it and so a human review gate is explicit.
+Do NOT add, rename, or drop files without bumping the template `schema_version` and the scanner's
+`SELF_DOC_SET` together (they are checked as a pair).
+
+These docs are COMMITTED (not gitignored) -- they are the shareable artefact, unlike the
+gitignored `.ai-assistance/local/` context that `ai-discovery` writes.
+
+---
+
+## Workflow
+
+1. **Scan.** Run `self_docs_scan.py --json`. Read the observation.
+2. **Reuse.** Pull facts from the existing inputs it lists. Only genuinely-missing semantic content
+   is yours to write.
+3. **Fill / refresh.** For each self-doc: if missing, copy the template and fill it; if present,
+   update only the sections whose underlying facts changed (structure, hot paths, status). Keep
+   `review_status: draft` on anything a human has not confirmed.
+4. **Batch heavy semantic work to Gemini.** For a large or unfamiliar repo, draft
+   ARCHITECTURE/OVERVIEW via the `gemini-assist` skill (no-training tier) rather than on
+   interactive Claude tokens -- per the token-frugality rule. Verify Gemini's output against the
+   scanner facts before writing.
+5. **Write the index + changelog (deterministic).** Run:
+   ```bash
+   python .ai-assistance/skills/project-self-docs/scripts/self_docs_scan.py --write
+   ```
+   This rewrites `docs/self-docs/self-docs-index.json` (the machine surface the hub reads) and
+   APPENDS one line per changed doc to `docs/self-docs/CHANGES.jsonl`. A no-op re-run appends
+   nothing -- this is what makes the capability idempotent.
+6. **Human review before any egress.** Leave publishing to a human-reviewed step (see below).
+
+---
+
+## Publish / egress -- CONFIGURABLE, default local-only (OPEN DECISION)
+
+The Confluence publish destination is an OPEN DECISION being made separately (existing EPAI space
+vs a new dedicated hub space vs the private EP-AI-MGMT space). Therefore:
+
+- **Default: write to the repo/local filesystem ONLY.** This skill does not push to Confluence.
+- The publish target is a PARAMETER, not a hardcoded value. When the decision is made, the egress
+  step becomes a call to the existing seed pipeline (`scripts/seed-epai-project-docs.py` pattern)
+  pointed at the chosen space, gated by human review.
+- <!-- TODO(hub-target): wire egress to the chosen Confluence space once the publish-target
+  decision lands. Until then, self-docs live in docs/self-docs/ and are consumed from git. -->
+
+Never emit `r` (a result) straight to a shared surface: a human review gate sits between the
+generated self-docs and any hub publish. This is a damping control -- keep it.
+
+---
+
+## Actuation
+
+- **Actor:** a developer (or `ai-discovery`/`project-cycle` calling this skill) IN THE REPO THAT
+  DOCUMENTS ITSELF, never an unattended agent -- and NEVER an ep-ai-standards session reaching into
+  another repo to generate that repo's self-docs. ep-ai-standards AUTHORS + DEPLOYS this skill and
+  AGGREGATES/publishes results; each repo RUNS it in its own session. (Running it on ep-ai-standards
+  ITSELF is fine -- that is why `docs/self-docs/` exists here.)
+- **Trigger / clock:** on demand; recommended at project cycle-end (`project-cycle`) and after a
+  structural change. There is no autonomous fleet-wide trigger yet -- that depends on the unbuilt
+  ADR-014 upkeep loop; note this rather than inventing an actuator.
+- **Coverage on neglect:** if self-docs are never refreshed, the scanner's `content_hash` +
+  `source_head` in the index let the hub (and `project-review`) flag them as stale. The doc is
+  never silently trusted; staleness is detectable.
+- **Write authority:** writes ONLY under the self-docs directory (default `docs/self-docs/`), plus
+  the KPI usage line. It does not touch source code, `.ai-assistance/local/`, git remotes, or any
+  network target.
+
+---
+
+## What you do not do
+
+- Do not invent a documentation format -- use the fixed self-doc set and templates.
+- Do not re-analyse the codebase from scratch -- reuse `ai-discovery`, `code-specs`, and the
+  scanner; propose running those skills if their inputs are missing.
+- Do not publish to Confluence or any network target -- egress is a separate, human-gated,
+  as-yet-undecided step.
+- Do not write outside `docs/self-docs/` (or the configured self-docs dir).
+- Do not run heavy semantic drafting on interactive Claude tokens for large repos -- batch to
+  Gemini (no-training tier).
+- Do not mark a doc `review_status: reviewed` -- only a human does that.