@nurix/etna 0.18.0 → 0.18.2

package/data/harnesses/discover/rules/cartography-flows.md

@@ -0,0 +1,99 @@
+# Cartography — UX Flows reference (Mode 4, artifact 2 of 3)
+
+The method + template for `evaluation/ux-flows.md`. Spine in [`cartography.md`](cartography.md); siblings
+[`cartography-ia.md`](cartography-ia.md), [`cartography-coverage.md`](cartography-coverage.md).
+
+The UX-flows doc captures the primary end-to-end journeys, each as a **mermaid sequence diagram**. This
+is the **black-box adaptation of a code-level workflow trace**: where a source tracer follows call
+chains, Cartography follows the **observed wire** — trigger (user action) → surface → the actual API
+calls captured in the `session` dimension → state transitions → terminal effect. **Diagram only what was
+observed**; mark any inferred hop explicitly.
+
+---
+
+## Participants (the black-box vocabulary)
+
+Map every actor in a captured flow to one of these participants (keep names identical across all
+diagrams — the same backend is the same participant everywhere):
+
+| Participant | What it is |
+| --- | --- |
+| `User` | the operator taking the action |
+| `SPA` | the client app (browser) |
+| `InternalAPI` | the app-own cookie/token API (the real transport — `/rest`, `/enrich`, `/graphql`, …) |
+| `PublicAPI` | the published developer/partner API — **only if the flow actually used it** |
+| `JobQueue` | an async batch / worker / job system (the work happens off-request) |
+| `Realtime` | a WS / SSE / long-poll channel |
+| `3rdParty` | a named external vendor (AI mesh, payments, CDP, email, telephony) |
+| `Store` | browser storage / client cache (Apollo, Redux-persist, IndexedDB) |
+
+---
+
+## Identifying the flows (from captured wire, not source)
+
+The entry points are the **captured journeys** in the `session` dimension — you already have the wire;
+this turns it into a journey. Per category, look for:
+
+- **Core action** — the primary write: the create / save / submit body + its server resolution
+  (`raw/write-flow.md`).
+- **Auth & session** — login → token/cookie → the authed read; the refresh path (`raw/auth-*.md`).
+- **Realtime** — the WS/SSE/long-poll lifecycle + the event catalog (or the **negative**: "dashboard is
+  REST-only" is a real flow finding, not a miss).
+- **Data pipeline** — import/export, ingest, sync, bulk/mass-action (often an async `JobQueue` flow).
+- **Configuration** — a model/setting change that ripples (e.g. add an attribute → completeness recompute).
+- **AI** — a generate/translate/agent call (`raw/*-wire.md`); note brokered-server-side vs client-direct.
+
+Trace each: trigger → which surface → the observed request(s) → branches (conflict/permission/feature
+flag → `alt`/`opt`) → loops (polling/retry/batch → `loop`) → the terminal effect (a persisted entity, a
+job id, a streamed result). Stop at the terminal write or external response.
+
+## Complexity (sets diagram detail)
+
+- **Steps** (distinct operations): 1–2 simple · 3–5 moderate · 6+ complex.
+- **Participants**: 2 simple · 3–4 moderate · 5+ complex.
+- **Branching** (`alt`/`opt`): 0 linear · 1–2 moderate · 3+ complex.
+- Async (polling / job / child workflow): +1 level.
+
+---
+
+## The output template — `evaluation/ux-flows.md`
+
+````markdown
+# <Target> — UX Flows
+## TL;DR                  (how the product gets work done: sync-REST vs async-job, where realtime lives,
+                           the approval/gate pattern, what's brokered server-side)
+## Flow index             (table: flow · category · trigger · participants · complexity)
+## <Category> flows       (Core action / Auth & session / Realtime / Data pipeline / Configuration / AI —
+                           skip empty categories)
+  ### <Flow name>
+  **Trigger · Surface · Observed?**  (observed-wire | partially-inferred)
+  ```mermaid
+  sequenceDiagram
+      participant User
+      participant SPA
+      participant InternalAPI
+      User->>SPA: <action>
+      SPA->>InternalAPI: <METHOD> <path>
+      InternalAPI-->>SPA: <status + shape>
+      SPA-->>User: <UI effect>
+  ```
+  **Notes:** (server-side resolution · the gate · the async hop · what was inferred vs observed)
+## Cross-dimension reconciliation  (the flow as the app runs it vs as the public API/docs describe it —
+                                    drift is a finding; published = fact, observed-drift = tentative)
+## Open questions
+````
+
+## Diagram rules (from the workflow-mapper discipline)
+
+1. **Arrows:** solid `->>` = request/call · dashed `-->>` = return/response. No dangling calls (every
+   request has a response or a noted fire-and-forget).
+2. **≤7 participants, ≤15 steps** per diagram. Past that, group with `rect` blocks / `Note over`, or
+   split into linked sub-diagrams.
+3. **`alt`** = a real workflow branch (conflict vs success), **`loop`** = poll / retry / batch (label
+   the condition), **`opt`** = a gated step (permission, feature flag) — not generic error handling.
+4. **Labels ≤8 words** — the action, not the implementation detail.
+5. **Consistent participant names** across every diagram.
+6. **The write-side rule (hard):** a flow that touches a **write / generate / launch** path on a
+   `write_side_observed: false` run is diagrammed **as inferred** (dashed arrows, an explicit
+   `Note over … : inferred (Pass-1 only)`), **never as observed** — this mirrors the evaluation
+   write-side cap, and drawing it solid is a Mode-5 Cartography defect.

package/data/harnesses/discover/rules/cartography-ia.md

@@ -0,0 +1,88 @@
+# Cartography — Information Architecture reference (Mode 4, artifact 1 of 3)
+
+The method + template for `evaluation/information-architecture.md`. Spine + inputs + orchestration are
+in [`cartography.md`](cartography.md); the other two artifacts in [`cartography-flows.md`](cartography-flows.md)
+and [`cartography-coverage.md`](cartography-coverage.md).
+
+The IA doc is the map of **how the product is organized for the operator**. Walk the live app
+(read-only, in-app nav — never a full reload mid-walk, ingestion §9.4); for every reachable surface
+record its **depth**, whether it is **promoted** or **buried**, its **operator capability**, its
+**route**, the **wire endpoints** it fires, and the **entities** it touches.
+
+---
+
+## The depth taxonomy (the load-bearing measure)
+
+A capability's _depth_ is the product's implicit priority signal — record it **numerically**:
+
+| Depth | Meaning | Example |
+| --- | --- | --- |
+| **D0** | a top-level nav destination (sidebar / top-bar item) | `Products`, `Settings` |
+| **D1** | a list / index under a D0 destination | the product grid; the attributes list |
+| **D2** | a detail / editor surface, or a tab within it | a product edit form; an attribute's config |
+| **D3+** | a sub-panel, modal, drawer, or nested tab | "Ask AI" panel; a variant-axis editor; a workflow-config sub-tab |
+
+**Promoted** = the capability is a D0/D1 first-class destination. **Buried** = it is only reachable at
+≥D2 (often D3+), behind a detail surface or a menu. Depth is what makes the two reconciliations below
+computable.
+
+---
+
+## The two reconciliations that matter
+
+1. **Positioning-vs-product (the buried flagship).** A feature the **marketing** promotes — a verb on
+   the homepage, a named hero capability — that lives at **≥D3** in the product is a real finding. Name
+   it; it feeds `feature-coverage.md`'s _buried flagships_ section. (A "Workflow engine" splashed on the
+   site but reached only via a product → menu → sub-tab is the canonical case.)
+2. **Unmarketed depth (the inverse).** A deep, powerful surface the marketing **never mentions** (a rich
+   admin/config/automation surface, a governance log, a bulk-action engine) is equally a finding — it
+   feeds `feature-coverage.md`'s _unmarketed depth_ section.
+
+Both are computed by comparing the **walked nav depth** (this doc) against the **claimed feature
+catalog** (`cartography-coverage.md`).
+
+---
+
+## Surface cards (the screen layer that realizes the entity spine)
+
+One card per **primary** surface (each D0 destination + each materially distinct D1 list and D2 detail
+surface). The card is the join between the IA and the data model:
+
+```markdown
+### <Surface name>   [route · depth Dn · promoted | buried]
+- **Capability:** what the operator can do here (read / create / edit / configure / run)
+- **Entities:**   the domain entities it surfaces (link → data-model-api-surface.md)
+- **Endpoints:**  the app-own wire calls it fires (link → _shared/api-path-catalog.md)
+- **Screenshot:** captures/screens/<nn>-<surface>.png   (or: gap — reason)
+```
+
+> **Cross-dimension reconciliation (a route that's in the bundle but not in the nav).** Diff the walked
+> nav against `deployed-client-bundle`'s `route-table.md`: a route present in the bundle but **never
+> reachable in the live nav** is a **dormant / unshipped surface** — a finding, not noise. (On a
+> server-rendered / RSC app, a bundle route count can overstate the client surface — fold that into the
+> note rather than reporting a phantom "unused routes" gap; ingestion §9.4 RSC check.)
+
+---
+
+## The output template — `evaluation/information-architecture.md`
+
+```markdown
+# <Target> — Information Architecture
+## TL;DR              (org-shape in 3–5 sentences: how many top-level destinations, what's promoted vs
+                       folded, the deepest important surface, the biggest positioning-vs-product gap)
+## Nav tree           (the full hierarchy as an indented tree or table: top-level → section → list →
+                       detail → sub-tab; tag each node with depth D0/D1/D2/… and [promoted]/[buried])
+## Surface cards      (one per primary surface — the card shape above)
+## Promoted vs buried  (the headline reconciliation: first-class destinations vs surfaces hidden N
+                        levels deep — name the surprises in BOTH directions: buried flagships AND
+                        unmarketed depth)
+## Admin / settings depth   (the configuration surfaces + how deep they sit)
+## Global affordances  (command palette, global search, create-anywhere, keyboard shortcuts — if present)
+## Cross-dimension reconciliation  (nav-as-walked vs the bundle route-table / docs IA — dormant/unshipped
+                                    routes are findings)
+## Open questions
+```
+
+> The IA doc **feeds** `feature-coverage.md`: every surface card's route + depth is what the coverage
+> matrix's `Located? · Route · depth` columns cite, and the promoted-vs-buried headline is what its
+> _buried flagships_ / _unmarketed depth_ sections draw from. Build the IA doc first, then coverage.

package/data/harnesses/discover/rules/cartography.md

@@ -0,0 +1,109 @@
+# Cartography Reference — Mode 4 spine (Information Architecture · UX Flows · Feature Coverage)
+
+The reference root for **Cartography** (`discover` harness, **Mode 4**). After Evaluation (Mode 3)
+reconciles the dimensions into the four rollups, Cartography makes the product **legible as a product**:
+it **re-enters the live product** (read-only nav) and compiles three experiential artifacts the
+dimension collectors structurally miss, then runs a **coverage gate** that reconciles every
+_marketed / documented_ feature against **where it actually lives in the product** and **whether the run
+walked it**.
+
+The blind spot it closes: a feature **hyped on the website but buried three levels deep** in the product
+— or marketed but **absent from this edition entirely**. Ingestion captures the _raw_ feature lists
+(`website`, `docs`, `community`) and the _entity spine + wire_ (`session`); none of those locate a
+feature in the nav, measure its depth, draw its journey, or save a screenshot.
+
+> **Why a distinct mode, not a phase of Evaluation.** Evaluation is **desk reconciliation** of
+> already-captured material. Cartography **re-enters the live product** to walk surfaces, measure nav
+> depth, and capture screenshots — work that needs the **browser singleton** (ingestion §7 rule 9) and
+> a marketed-feature checklist to drive it. It runs **after** Evaluation (so the entity spine +
+> claimed-feature catalog exist) and **before** Self-correction (Mode 5), so the **coverage scorecard**
+> it emits feeds the score and the within-run re-walk.
+
+---
+
+## The Cartography family (this spine + three artifact references)
+
+This file is the **spine** — the inputs, the orchestration, the scorecard handoff, the ethics, the
+degraded modes. Each of the three artifacts has its own focused reference; **read the matching one when
+building that artifact**:
+
+| Artifact (output) | Governing reference | One-line |
+| --- | --- | --- |
+| `evaluation/information-architecture.md` | [`cartography-ia.md`](cartography-ia.md) | nav tree + per-surface cards, tagged with **depth** + **promoted\|buried** |
+| `evaluation/ux-flows.md` | [`cartography-flows.md`](cartography-flows.md) | primary journeys as mermaid sequence diagrams, traced from the **observed wire** |
+| `evaluation/feature-coverage.md` + `dimensions/session/captures/screens/` | [`cartography-coverage.md`](cartography-coverage.md) | the **claimed-vs-located-vs-walked** matrix + the **coverage scorecard** + the screenshots |
+
+> **Degraded modes are recorded, never faked.** When `auth` is `none` / there is **no authenticated app
+> surface**, Cartography maps only the **public** surfaces (marketing IA + docs IA + the unauth app
+> shell from `deployed-client-bundle`) and records the authed-surface gap in the scorecard. When the
+> live runtime can't be screenshotted (no image tool, or the app never reaches page-idle because of a
+> persistent connection — ingestion §9.5), the **textual surface-map is the accepted fallback** and the
+> `screenshot_coverage` gap is recorded. Cartography never fabricates an IA it could not navigate.
+
+---
+
+## Inputs (read these first)
+
+- `evaluation/product-features.md` + `dimensions/website/raw/features.md` + `dimensions/docs/raw/*` —
+  the **claimed feature catalog**: the checklist Cartography must locate. (Community/changelog feature
+  claims fold in too.) → drives `cartography-coverage.md`.
+- `evaluation/data-model-api-surface.md` + `dimensions/session/raw/*` — the **entity spine** + the
+  observed endpoints, so each surface card names the entities + wire calls it touches → drives
+  `cartography-ia.md`; the captured wires (`raw/write-flow.md`, `raw/*-wire.md`, the auth fingerprint)
+  are the source for `cartography-flows.md`.
+- `dimensions/session/captures/surface-map.md` + `dimensions/deployed-client-bundle/raw/route-table.md` —
+  the **route / nav inventory** to walk (the coverage checklist of surfaces, ingestion §9.4).
+- `dimensions/session/_summary.md` `write_side_observed` / `pass2` flags — gate whether a write/generate
+  flow can be diagrammed from **observation** or must be marked **inferred** (ingestion §9.2;
+  `cartography-flows.md`).
+
+---
+
+## The coverage scorecard (the machine-readable handoff to Mode 5)
+
+The single load-bearing output of Cartography for the self-correcting loop. It is produced as the
+frontmatter of `feature-coverage.md` (schema + scoring in `cartography-coverage.md`) and read by
+**Self-correction (Mode 5)** two ways:
+
+1. **Scores the experiential / IA coverage axis** (the heavily-weighted rubric axis) from
+   `feature_location_rate`, `flow_coverage`, `screenshot_coverage`, `ia_nav_complete`.
+2. **Drives the within-run re-walk** from the `located-but-not-walked` queue: Mode 5 re-enters the live
+   product (read-only nav), walks the not-yet-walked surfaces, captures the missed screenshots, and
+   locates any _deeper-than-looked_ marketed feature — then re-runs Mode 4 and re-scores.
+
+A `claimed-but-not-located` feature is **never silently dropped** — it is always dispositioned
+(_deeper-than-looked_ → the re-walk queue · _edition/plan-gated_ and _roadmap-not-shipped_ → a recorded
+gap, not re-walked · _marketing over-claim_ → an `evaluation/product-features.md` over-claim flag).
+
+---
+
+## How Mode 4 is driven
+
+By the **main session** — it owns the browser singleton (ingestion §7 rule 9), and Cartography
+re-enters the live product. Steps:
+
+1. Read the inputs (the claimed-feature catalog, the entity spine, the route/nav inventory).
+2. **Walk the live product read-only**, section by section, via in-app nav (never a full reload
+   mid-walk, ingestion §9.4). Per surface: record depth + capability + route + the endpoints it fires +
+   capture a screenshot. _(method per `cartography-ia.md`)_
+3. Compile `information-architecture.md` (`cartography-ia.md`).
+4. Turn the captured `session` wires into the `ux-flows.md` sequence diagrams (`cartography-flows.md`).
+5. Build the `feature-coverage.md` matrix + emit the **coverage scorecard** (`cartography-coverage.md`).
+
+The main session **MAY dispatch sub-agents** (`model: opus`) to _draft_ the three docs from
+already-captured material (overlapping reads, independent writes) — but the **live walk + screenshots
+are main-session only** (browser singleton). **Read-only / no-cost only:** locating a feature never
+requires triggering it — any write/generate/launch trigger stays behind the Pass-2 confirmation gate
+(ingestion §7 rule 4, §9.2), never fired to "see" a feature. **Absences are findings, never silent
+drops** — a claimed-but-not-located feature, an unmapped nav destination, and an undiagrammed primary
+flow are each recorded, and the scorecard makes the gaps machine-readable for Mode 5.
+
+---
+
+## How the modes use this family
+
+Mode 4 reads this spine for the inputs + orchestration + scorecard contract, then the three artifact
+references for each deliverable's method + template. Mode 5 reads the **scorecard** (here) + the
+**Cartography defect category** (`self-correction.md` stage A) to score the experiential axis and drive
+the within-run re-walk. Evaluation's rollups are Cartography's inputs (`evaluation.md`); Cartography's
+screenshots complete the session playbook's surface-map (ingestion §9.5).