docs(skills): document /trade trade-market-route-summary in AGENTS_FRONTEND_SWAP_ROUTE_DISPLAY (#302) #321

New issue

2026-06-05T05:42:24Z

PlasticDigits commented

2026-06-05 05:42:24 +00:00

(Migrated from gitlab.com)

Current codebase

Product behavior (shipped): GitLab #302 / MR !758 added an execution-aligned Route row to the /trade market order quote card, mirroring /swap (computeSwapRouteDisplay).

Surface	`data-testid`	Code
`/swap` trade summary	`swap-route-summary`	`frontend-dapp/src/pages/SwapPage.tsx`
`/trade` market quote	`trade-market-route-summary`	`frontend-dapp/src/components/trade/TradeMarketOrderPanel.tsx`

TradeMarketOrderPanel passes simQuery.data?.indexerOperations into computeSwapRouteDisplay with clientRoute: null and isDirect: true (direct pair context; indexer ops win when present).

Agent / docs gap: skills/AGENTS_FRONTEND_SWAP_ROUTE_DISPLAY.md was written for GitLab #158 (swap-only). It lists only SwapPage.tsx / swap-route-summary in the code map and regression checklist. It does not mention:

/trade market panel or trade-market-route-summary
When route appears (hybrid + postRouteSolve / indexerOperations vs pool-only quote)
Link to #302 or docs/frontend.md trade market section

docs/frontend.md documents route preview under Swap integration (#158) but not the trade market quote card (#302).

Why this is needed

Agent guardrails: Cloud Agents editing route display must not regress /trade when following the swap-only skill.
Verification traceability: #302 verification noted missing cross-links; docs drift causes repeat manual discovery.
Single invariant: One shared util (computeSwapRouteDisplay) serves two surfaces — documentation should match.

Constraints and guardrails

Execution-aligned path (#158): Display must match submit path on each page (SwapPage swap mutation vs TradeMarketOrderPanel market mutation / swapOpsRequireRouter).
One route row: No duplicate Route (indexer) labels on either surface.
Trade-specific: Route row renders only when marketRouteLine is non-null (inside trade-market-quote); pool-only quotes may show direct from → to via isDirect branch without multihop ops.
Do not document fallback-indicator behavior here unless implemented (tracked separately on #302 follow-up).
Keep skill concise; link to docs/swap-max-spread-ux.md and docs/indexer-invariants.md rather than duplicating L8/hybrid prose.

Relevant files

File	Role
`skills/AGENTS_FRONTEND_SWAP_ROUTE_DISPLAY.md`	Primary — extend code map, checklist, cross-links
`frontend-dapp/src/components/trade/TradeMarketOrderPanel.tsx`	Route UI + `indexerOperations` wiring (#302)
`frontend-dapp/src/pages/SwapPage.tsx`	Swap route UI (#158)
`frontend-dapp/src/utils/swapRouteDisplay.ts`	Shared display logic
`frontend-dapp/src/utils/swapRouteDisplay.test.ts`	Unit tests
`docs/frontend.md`	Optional short § under Trade / market order pointing to skill + `trade-market-route-summary`
`docs/swap-max-spread-ux.md`	Invariant #5 (route preview)
`AGENTS.md`	Optional one-line pointer under frontend skills

Acceptance criteria

skills/AGENTS_FRONTEND_SWAP_ROUTE_DISPLAY.md documents both swap-route-summary and trade-market-route-summary with file paths and #302 reference.
Skill explains that both surfaces use computeSwapRouteDisplay and indexer op precedence (#158).
Manual regression checklist includes at least one /trade market step.
docs/frontend.md (or docs/swap-max-spread-ux.md) links to the skill for trade market route (minimal paragraph).
No contradictory text implying route is swap-only.

Test plan (functional paths)

Path	Steps	Expected
Doc review	Read updated skill end-to-end	Matches current `TradeMarketOrderPanel` + `SwapPage` behavior
Swap regression	Existing skill swap checklist (4 steps)	Unchanged intent
Trade manual	Local stack: `/trade/<EMBER/COBALT pair>`, Market, hybrid on, amount `1`	`trade-market-route-summary` visible with `Route` label
Trade pool-only	Hybrid off, amount set	Quote may show; route line direct `A → B` or hidden per `marketRouteLine` null rules — document actual behavior
Unit	`npm run test:run -- swapRouteDisplay.test.ts`	Pass (no code change expected)

Test plan (attack / abuse / misleading UX)

Vector	Risk	Mitigation / check
Display ≠ execute	User trusts wrong path on `/trade`	Skill stresses execution alignment; checklist includes small on-chain swap vs displayed hop count
Fake route row	Testid present but empty/misleading	Document that row renders only when `marketRouteLine` truthy
Duplicate route labels	Phishing-style extra route strip	Skill reiterates single row invariant (#158) on both pages
Indexer outage	Stale route from cached ops	Cross-link `AGENTS_FRONTEND_MARKET_DATA_OUTAGE.md` / quote disclosure behavior (no new scope)

Verification criteria

Agent can find /trade route testid and panel file from skill alone (no grep required).
#302 verification comment checklist can cite this skill for regression steps.
MR is docs-only; make lint / no frontend code change, or trivial link fixes only.
Reviewer confirms docs/frontend.md and skill do not contradict TradeMarketOrderPanel.tsx.

GitLab #302 — OE-6 trade route display (implementation merged !758)
GitLab #158 — single swap route row
GitLab #152 — trade market order panel

## Current codebase **Product behavior (shipped):** GitLab **#302** / MR !758 added an execution-aligned **Route** row to the `/trade` market order quote card, mirroring `/swap` ([`computeSwapRouteDisplay`](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/blob/main/frontend-dapp/src/utils/swapRouteDisplay.ts)). | Surface | `data-testid` | Code | |---------|---------------|------| | `/swap` trade summary | `swap-route-summary` | `frontend-dapp/src/pages/SwapPage.tsx` | | `/trade` market quote | `trade-market-route-summary` | `frontend-dapp/src/components/trade/TradeMarketOrderPanel.tsx` | `TradeMarketOrderPanel` passes `simQuery.data?.indexerOperations` into `computeSwapRouteDisplay` with `clientRoute: null` and `isDirect: true` (direct pair context; indexer ops win when present). **Agent / docs gap:** [`skills/AGENTS_FRONTEND_SWAP_ROUTE_DISPLAY.md`](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/blob/main/skills/AGENTS_FRONTEND_SWAP_ROUTE_DISPLAY.md) was written for GitLab **#158** (swap-only). It lists only `SwapPage.tsx` / `swap-route-summary` in the code map and regression checklist. It does **not** mention: - `/trade` market panel or `trade-market-route-summary` - When route appears (hybrid + `postRouteSolve` / `indexerOperations` vs pool-only quote) - Link to #302 or [`docs/frontend.md`](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/blob/main/docs/frontend.md) trade market section **`docs/frontend.md`** documents route preview under Swap integration (#158) but not the trade market quote card (#302). ## Why this is needed - **Agent guardrails:** Cloud Agents editing route display must not regress `/trade` when following the swap-only skill. - **Verification traceability:** #302 verification noted missing cross-links; docs drift causes repeat manual discovery. - **Single invariant:** One shared util (`computeSwapRouteDisplay`) serves two surfaces — documentation should match. ## Constraints and guardrails - **Execution-aligned path (#158):** Display must match submit path on each page (`SwapPage` swap mutation vs `TradeMarketOrderPanel` market mutation / `swapOpsRequireRouter`). - **One route row:** No duplicate `Route (indexer)` labels on either surface. - **Trade-specific:** Route row renders only when `marketRouteLine` is non-null (inside `trade-market-quote`); pool-only quotes may show direct `from → to` via `isDirect` branch without multihop ops. - **Do not** document fallback-indicator behavior here unless implemented (tracked separately on #302 follow-up). - Keep skill concise; link to `docs/swap-max-spread-ux.md` and `docs/indexer-invariants.md` rather than duplicating L8/hybrid prose. ## Relevant files | File | Role | |------|------| | `skills/AGENTS_FRONTEND_SWAP_ROUTE_DISPLAY.md` | **Primary** — extend code map, checklist, cross-links | | `frontend-dapp/src/components/trade/TradeMarketOrderPanel.tsx` | Route UI + `indexerOperations` wiring (#302) | | `frontend-dapp/src/pages/SwapPage.tsx` | Swap route UI (#158) | | `frontend-dapp/src/utils/swapRouteDisplay.ts` | Shared display logic | | `frontend-dapp/src/utils/swapRouteDisplay.test.ts` | Unit tests | | `docs/frontend.md` | Optional short § under Trade / market order pointing to skill + `trade-market-route-summary` | | `docs/swap-max-spread-ux.md` | Invariant #5 (route preview) | | `AGENTS.md` | Optional one-line pointer under frontend skills | ## Recommended solution direction 1. **Rename or subtitle skill** (optional): e.g. “Swap & trade market — single route row” so scope is obvious without breaking existing links. 2. **Code map table** — add row: - Trade market quote: `TradeMarketOrderPanel.tsx` — `data-testid="trade-market-route-summary"` - Submit: same file — `swapMutation` / `indexerOperations` / `executeMultiHopSwap` 3. **Product invariant** — bullet: `/trade` market quote shows the same single **Route** row when indexer-shaped ops are present. 4. **Regression checklist** — add manual steps: - `/trade/:pairAddr` → Market tab → hybrid on → amount → confirm `trade-market-route-summary` visible. - Multihop: pair where indexer returns ≥2 hops (e.g. EMBER→COBALT via `GET /route/solve`) with hybrid enabled; route shows ≥3 symbols. 5. **Cross-links:** GitLab #302, #158, `docs/frontend.md` trade section (add anchor if missing). 6. **No production code change required** unless docs reveal a bug; this issue is documentation-only. ## Acceptance criteria - [ ] `skills/AGENTS_FRONTEND_SWAP_ROUTE_DISPLAY.md` documents both `swap-route-summary` and `trade-market-route-summary` with file paths and #302 reference. - [ ] Skill explains that both surfaces use `computeSwapRouteDisplay` and indexer op precedence (#158). - [ ] Manual regression checklist includes at least one `/trade` market step. - [ ] `docs/frontend.md` (or `docs/swap-max-spread-ux.md`) links to the skill for trade market route (minimal paragraph). - [ ] No contradictory text implying route is swap-only. ## Test plan (functional paths) | Path | Steps | Expected | |------|--------|----------| | Doc review | Read updated skill end-to-end | Matches current `TradeMarketOrderPanel` + `SwapPage` behavior | | Swap regression | Existing skill swap checklist (4 steps) | Unchanged intent | | Trade manual | Local stack: `/trade/<EMBER/COBALT pair>`, Market, hybrid on, amount `1` | `trade-market-route-summary` visible with `Route` label | | Trade pool-only | Hybrid off, amount set | Quote may show; route line direct `A → B` or hidden per `marketRouteLine` null rules — document actual behavior | | Unit | `npm run test:run -- swapRouteDisplay.test.ts` | Pass (no code change expected) | ## Test plan (attack / abuse / misleading UX) | Vector | Risk | Mitigation / check | |--------|------|-------------------| | **Display ≠ execute** | User trusts wrong path on `/trade` | Skill stresses execution alignment; checklist includes small on-chain swap vs displayed hop count | | **Fake route row** | Testid present but empty/misleading | Document that row renders only when `marketRouteLine` truthy | | **Duplicate route labels** | Phishing-style extra route strip | Skill reiterates single row invariant (#158) on both pages | | **Indexer outage** | Stale route from cached ops | Cross-link `AGENTS_FRONTEND_MARKET_DATA_OUTAGE.md` / quote disclosure behavior (no new scope) | ## Verification criteria - [ ] Agent can find `/trade` route testid and panel file from skill alone (no grep required). - [ ] #302 verification comment checklist can cite this skill for regression steps. - [ ] MR is docs-only; `make lint` / no frontend code change, or trivial link fixes only. - [ ] Reviewer confirms `docs/frontend.md` and skill do not contradict `TradeMarketOrderPanel.tsx`. ## Related - GitLab **#302** — OE-6 trade route display (implementation merged !758) - GitLab **#158** — single swap route row - GitLab **#152** — trade market order panel

PlasticDigits commented

2026-06-05 05:42:34 +00:00

(Migrated from gitlab.com)

marked as related to #302

PlasticDigits commented

2026-06-05 05:42:35 +00:00

(Migrated from gitlab.com)

marked as related to #158

ghost1 commented

2026-06-05 10:06:39 +00:00

(Migrated from gitlab.com)

mentioned in commit 5d3917c4dc

mentioned in commit 5d3917c4dca3550ff4111c7309fd0b47955f9fe8

PlasticDigits commented

2026-06-05 10:07:06 +00:00

(Migrated from gitlab.com)

mentioned in merge request !788

PlasticDigits commented

2026-06-05 10:07:13 +00:00

(Migrated from gitlab.com)

Implementation complete — MR !788

Docs-only update for https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/work_items/321

MR: https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/merge_requests/70

Changes

skills/AGENTS_FRONTEND_SWAP_ROUTE_DISPLAY.md — renamed scope to “Swap & trade market”; added trade-market-route-summary code map, when-route-appears table, /trade regression steps (5–8), cross-links to #302 / docs/frontend.md#trade-page-market-context.
docs/frontend.md — market route preview row in #trade-page-market-context.
docs/swap-max-spread-ux.md — invariant #6 mentions Trade market (#302).
AGENTS.md — one-line skill pointer.

Acceptance criteria

Criterion	Result	How verified
Skill documents both testids + paths + #302	PASS	Code map + cross-links in updated skill
Shared `computeSwapRouteDisplay` + indexer precedence	PASS	Product invariant + code map
Manual checklist includes `/trade` market step	PASS	Checklist steps 5–8
`docs/frontend.md` links skill for trade market route	PASS	`#trade-page-market-context` table row
No swap-only contradictory text	PASS	Doc review + grep

Tests

Check	Result
`npm run test:run -- swapRouteDisplay.test.ts`	PASS (4/4)
`python3 scripts/check_fee_discount_tier_docs.py`	PASS
Trade manual QA (local stack)	SKIP — procedure documented in skill step 5; no code change

Issue left open pending MR merge.

## Implementation complete — MR !788 Docs-only update for https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/work_items/321 **MR:** https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/merge_requests/70 ### Changes - `skills/AGENTS_FRONTEND_SWAP_ROUTE_DISPLAY.md` — renamed scope to “Swap & trade market”; added `trade-market-route-summary` code map, when-route-appears table, `/trade` regression steps (5–8), cross-links to #302 / `docs/frontend.md#trade-page-market-context`. - `docs/frontend.md` — market route preview row in `#trade-page-market-context`. - `docs/swap-max-spread-ux.md` — invariant #6 mentions Trade market (#302). - `AGENTS.md` — one-line skill pointer. ### Acceptance criteria | Criterion | Result | How verified | |-----------|--------|--------------| | Skill documents both testids + paths + #302 | **PASS** | Code map + cross-links in updated skill | | Shared `computeSwapRouteDisplay` + indexer precedence | **PASS** | Product invariant + code map | | Manual checklist includes `/trade` market step | **PASS** | Checklist steps 5–8 | | `docs/frontend.md` links skill for trade market route | **PASS** | `#trade-page-market-context` table row | | No swap-only contradictory text | **PASS** | Doc review + grep | ### Tests | Check | Result | |-------|--------| | `npm run test:run -- swapRouteDisplay.test.ts` | **PASS** (4/4) | | `python3 scripts/check_fee_discount_tier_docs.py` | **PASS** | | Trade manual QA (local stack) | **SKIP** — procedure documented in skill step 5; no code change | Issue left **open** pending MR merge.

PlasticDigits commented

2026-06-05 10:36:23 +00:00

(Migrated from gitlab.com)

mentioned in commit 637f4e7712

mentioned in commit 637f4e7712a4e9a4a419dece89ae032c54f47ad9

PlasticDigits commented

2026-06-05 11:37:06 +00:00

(Migrated from gitlab.com)

Verification complete — GitLab #321

Issue: https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/work_items/321

Implementation landed in MR !788 (merged). This verification run confirms acceptance criteria on main without additional repo changes.

Acceptance criteria

Criterion	Result	How verified
Skill documents both `swap-route-summary` and `trade-market-route-summary` with paths + #302	PASS	Read `skills/AGENTS_FRONTEND_SWAP_ROUTE_DISPLAY.md` — code map rows 24–28, product invariant § Trade market, cross-links to #302
Shared `computeSwapRouteDisplay` + indexer op precedence (#158)	PASS	Skill product invariant + code map; matches `TradeMarketOrderPanel.tsx` (`indexerOperations`, `clientRoute: null`, `isDirect: true`)
Manual regression checklist includes `/trade` market step	PASS	Skill checklist steps 5–8 under “Trade market”
`docs/frontend.md` links skill for trade market route	PASS	`#trade-page-market-context` table row “Market quote — route preview (#302)”
No contradictory swap-only text	PASS	`rg -i 'swap-only

Verification criteria

Criterion	Result	How verified
Agent can find `/trade` testid + panel from skill alone	PASS	Code map points to `TradeMarketOrderPanel.tsx` + `trade-market-route-summary`
#302 verification can cite skill for regression	PASS	Checklist steps 5–8 + when-route-appears table
Docs-only MR / no frontend code change	PASS	MR !788 merged; `git status` clean on verify branch
`docs/frontend.md` + skill match `TradeMarketOrderPanel.tsx`	PASS	Code review: `marketRouteLine` gated render at `trade-market-route-summary`

Automated tests

Check	Command	Result
Unit tests	`cd frontend-dapp && npm run test:run -- swapRouteDisplay.test.ts`	PASS (4/4)
Docs drift	`python3 scripts/check_fee_discount_tier_docs.py`	PASS

Manual / functional QA (local stack)

LocalTerra + indexer + frontend started via scripts/setup-cloud-agent-localterra.sh --start-frontend.

Path	Steps	Result
Trade hybrid on	`/trade/terra1a5wvh2f0…` (EMBER/COBALT) → Market → hybrid on → amount `1`	PASS — `trade-market-route-summary` visible with Route label (Playwright smoke, 2 workers)
Trade pool-only	Same pair, hybrid off, amount `1`	PASS — quote visible; direct `→` route when row present

Playwright command (ephemeral spec, not committed):

sg docker -c 'npx playwright test e2e/verify-issue-321-trade-route.spec.ts --workers=5'

Outcome

All acceptance and verification criteria PASS. Closing issue.

## Verification complete — GitLab #321 Issue: https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/work_items/321 Implementation landed in **MR !788** (merged). This verification run confirms acceptance criteria on `main` without additional repo changes. ### Acceptance criteria | Criterion | Result | How verified | |-----------|--------|--------------| | Skill documents both `swap-route-summary` and `trade-market-route-summary` with paths + #302 | **PASS** | Read `skills/AGENTS_FRONTEND_SWAP_ROUTE_DISPLAY.md` — code map rows 24–28, product invariant § Trade market, cross-links to #302 | | Shared `computeSwapRouteDisplay` + indexer op precedence (#158) | **PASS** | Skill product invariant + code map; matches `TradeMarketOrderPanel.tsx` (`indexerOperations`, `clientRoute: null`, `isDirect: true`) | | Manual regression checklist includes `/trade` market step | **PASS** | Skill checklist steps 5–8 under “Trade market” | | `docs/frontend.md` links skill for trade market route | **PASS** | `#trade-page-market-context` table row “Market quote — route preview (#302)” | | No contradictory swap-only text | **PASS** | `rg -i 'swap-only|swap only'` on skill/docs — no route-is-swap-only claims | ### Verification criteria | Criterion | Result | How verified | |-----------|--------|--------------| | Agent can find `/trade` testid + panel from skill alone | **PASS** | Code map points to `TradeMarketOrderPanel.tsx` + `trade-market-route-summary` | | #302 verification can cite skill for regression | **PASS** | Checklist steps 5–8 + when-route-appears table | | Docs-only MR / no frontend code change | **PASS** | MR !788 merged; `git status` clean on verify branch | | `docs/frontend.md` + skill match `TradeMarketOrderPanel.tsx` | **PASS** | Code review: `marketRouteLine` gated render at `trade-market-route-summary` | ### Automated tests | Check | Command | Result | |-------|---------|--------| | Unit tests | `cd frontend-dapp && npm run test:run -- swapRouteDisplay.test.ts` | **PASS** (4/4) | | Docs drift | `python3 scripts/check_fee_discount_tier_docs.py` | **PASS** | ### Manual / functional QA (local stack) LocalTerra + indexer + frontend started via `scripts/setup-cloud-agent-localterra.sh --start-frontend`. | Path | Steps | Result | |------|--------|--------| | Trade hybrid on | `/trade/terra1a5wvh2f0…` (EMBER/COBALT) → Market → hybrid on → amount `1` | **PASS** — `trade-market-route-summary` visible with **Route** label (Playwright smoke, 2 workers) | | Trade pool-only | Same pair, hybrid off, amount `1` | **PASS** — quote visible; direct `→` route when row present | Playwright command (ephemeral spec, not committed): ```bash sg docker -c 'npx playwright test e2e/verify-issue-321-trade-route.spec.ts --workers=5' ``` ### Outcome All acceptance and verification criteria **PASS**. Closing issue.

PlasticDigits (Migrated from gitlab.com) closed this issue

2026-06-05 11:37:06 +00:00

Sign in to join this conversation.