---
description: SRS-34 — semantic normalization of experiences-list.json after listExperiences; XP/BH codes; JSON only; .easyspecs/context; repo-grounded views (no invented UIs).
mode: primary
---

# Agent: Experiences list — semantic review (coordination JSON)

| Field | Value |
| ----- | ----- |
| **AGENT_ID** | `ctx-review-experiences-list` |
| **Display name** | Experiences list — semantic review |
| **Output** | `<worktree>/.easyspecs/context/experiences-list.json` (overwrite) |

## Responsibility

**`.opencode/` and `.claude/` exclusion:** The worktree may contain **`.opencode/`** or **`.claude/`** (materialized coding agent definitions, schemas, and tooling). It is **not** part of the analyzed product codebase. **Do not** use it to infer application behavior. **Never** cite paths under **`.opencode/`** or **`.claude/`** in **`sourceReferences`**, UI/backend evidence arrays, Evidence index bullets, **`evidenceRefs`**, or any other code-grounding output.

Read the existing **experiences-list.json** (schema-valid from **listExperiences**). Rewrite as canonical: merge duplicate views/interactions, remove false XP/BH rows, fix split/merge; each **view** and **interaction** **must** have **`sourceReferences`** with **`minItems: 1`** (add evidence or **drop** the row). Keep stable **XP-*** / **BH-*** codes. Append **revisionLog** if the schema supports it.

**Critical:** A **view** is any **user-facing surface** the product exposes for interaction—not only full graphical windows. Treat **command-line usage** (subcommands, REPLs, prompts, stdin/stdout flows) and **terminal UIs** (TUI) as first-class views when the repo implements them. **Do not assume** the project is a web app or a single-page stack.

## Implementation-only (SRS-114)

Document **only** what is **implemented in this repository today**. Do **not** add knowledge nodes for planned, missing, roadmap, or spec-only capabilities.

- **Include** a row or detail section **only** when you can cite **implementation evidence** (§3.1 in SRS-114): wired entrypoints, executable bodies, real UI artefacts, schemas in use, or behavioural tests (QA/TC).
- **Omit** the node entirely when you find only SRS, PLAN, README, comments, types without callers, empty stubs, or configs nothing reads.
- **`sourceReferences`** and **Evidence index** **must** include **at least one implementation anchor** (non-`.md` path per §5.6.2). **`.md`** files (SRS, README, plans) **may** be cited **in addition**, never as the **only** cites.
- **Review passes:** drop unimplemented rows like false rows; log **`droppedCodes`** / **`revisionLog`** (SRS-50).
- **Do not** fill coordination lists with placeholders for future work. An empty array is valid when nothing is implemented.


## Reference coverage expansion (SRS-127)

After semantic normalization, **expand reference coverage** on **every surviving row** so zero-reference remediation has less work later.

**Per row — mandatory expansion pass:**

1. Start from existing **`sourceReferences`** (entry points). Open those files and trace **outward**: imports, re-exports, callers, sibling modules in the same feature area, route registration, store/actions, UI components, migrations, fixtures, and CI/script wiring that implements **this row only**.
2. Add **`sourceReferences`** for **each distinct implementation file** in that row's footprint — **one object per file** with accurate **`startLine` / `endLine`** spans (not whole-file lazy ranges when narrower spans exist).
3. **Do not stop at minItems: 1.** The validation minimum is not the target. Aim to cite **all** repo files that implement this row before detail markdown and remediation run.
4. **Dedupe** — do not append identical path+range entries.
5. **SRS-114** — every row keeps **≥1** non-`.md` implementation anchor; markdown may supplement.
6. **`revisionLog`** — append a summary noting expansion (e.g. *SRS-127: expanded sourceReferences for FE-03*).

**Discovery hints:** Prefer product **`src/`**, **`test/`**, **`scripts/`** invoked by package/CI manifests, config consumed by cited code. Skip always-forbidden paths (`.easyspecs/context/`, `.gluecharm/context/`, `.opencode/`, `.claude/`).

**When unsure** whether a file belongs to this row vs another: cite only if the file **primarily** serves this row's capability; leave ambiguous files for remediation — do **not** cite unrelated modules to inflate counts.


## SRS-50 (stable coordination list writes)

- **Append-only** — net-new `XP-*` rows (and nested `BH-*`) only **after** existing rows at each level; **do not reorder** surviving rows.
- **Logged deletes** — **`revisionLog[].droppedCodes`** must list every removed `code` (exact strings).
- **Slug rename auth** — **`revisionLog[].slugRenames`** `{ code, from, to }` when changing `slug` without changing `code`.

## Reasoning workflow (mandatory order)

Work through these steps **explicitly** (brief notes in your own trace are fine; the **deliverable** remains the JSON file only). Skipping classification and jumping to “pages/routes” causes **hallucinated views**.

### 1. Classify UI paradigm(s) for this repository

Before naming views, infer from **evidence under `{{WORKTREE_ROOT}}`** (build files, entrypoints, frameworks, docs—not guesses):

- **Web** (browser): SPAs, SSR, static sites, server-rendered HTML.
- **Desktop GUI**: native or cross-platform windowing (e.g. Electron, Qt, WPF, WinForms, **Embarcadero Delphi/VCL/FMX**, etc.).
- **CLI / terminal**: binaries, scripts, `argparse`/cobra/clap-style CLIs, interactive prompts.
- **TUI**: ncurses, bubbletea, textual, etc.
- **Hybrid**: e.g. desktop shell + embedded webview, or CLI + optional GUI.
- **Library / headless**: if there is **no** end-user UI in this repo, reflect that honestly—do not invent screens; align list rows with what actually exists (API-only packages may have **no** XP views, or only “usage via API/docs” if the schema allows).

If multiple paradigms apply, **list each** and later assign views to the correct paradigm.

### 2. Map “where views live” to the stack (non-linear)

Do **not** use a single template (e.g. “always Vue routes”). For each paradigm you identified, decide **which artifacts constitute a distinct user interface**:

| Paradigm | Typical grounding (examples—verify in repo) |
| -------- | -------------------------------------------- |
| Web | Route tables, page components, app shells, server templates |
| Desktop (generic) | Windows/forms/scenes, XAML, storyboards, main window entry |
| **Delphi (Object Pascal)** | **Forms**: paired **`.dfm`** (layout) **+** **`.pas`** units (behavior); projects **`.dproj` / `.dpr`**; frames and datamodules may compose multiple surfaces—one **logical** form/dialog can be one view or split per user task per list rules |
| CLI | Main entry, command dispatchers, help text, config flags, subcommand modules |
| TUI | Screen definitions, keymaps, panel layouts |
| Extension / IDE | `package.json` contributions, webview panels, commands |

**Delphi note:** Discovery is **not** linear like “one folder = one page.” Follow **project file → units → forms**: a `.dfm` names a form class; the matching `.pas` holds code. Count **user-openable** forms/dialogs/wizards the product actually ships, not every internal data module unless the user interacts with it as a surface.

### 3. Ground every retained or new view row

For each experience/view row you keep or add:

- There must be **at least one** plausible **source reference** (path to implementation: form unit, route file, CLI module, etc.) **or** explicit evidence that the prior list row was already correct—**never** invent routes, forms, or “screens” with no file/project backing.
- If **listExperiences** proposed a view you cannot verify, **remove or merge** it into a verified sibling; do not leave placeholder views to satisfy a mental model of “what a normal app has.”
- Prefer **fewer, accurate** views over **many, speculative** ones.

### 4. Normalize (original duty)

Merge duplicates, fix XP/BH codes and slits, preserve valid **sourceReferences**, append **revisionLog** when supported.

## Task (for `{{LIST_TASK_DESCRIPTION}}`)

Execute the **reasoning workflow**, then normalize per **Responsibility**. Output one JSON at **`{{OUTPUT_FILE_ABSOLUTE}}`** validating against **`{{LIST_SCHEMA_REF}}`**.

### JSON string literals (RFC 8259 — mandatory)

- Coordination artefacts use **double-quoted** JSON strings only.
- **Apostrophes / single quotes** inside text (e.g. user's, don't, it's) **must appear as the plain character** `'` — **never** as `\'`. In JSON, `\'` is **invalid** and causes `JSON.parse` to fail with *Bad escaped character*.
- **Only** escape `"` as `\"`, backslashes as `\\`, and use `\n`, `\t`, `\uXXXX` where needed. Do **not** use Python-, SQL-, or JavaScript-single-quote escaping in `.json` files.
- **Examples (description field):**
  - ✅ `"description": "API endpoint to update a user's password."`
  - ❌ `"description": "API endpoint to update a user\'s password."`

## Harness wiring

Use **`{{LIST_SCHEMA_REF}}`**, **`{{WORKTREE_ROOT}}`**, **`{{OUTPUT_FILE_ABSOLUTE}}`**, **`{{OUTPUT_BASENAME}}`**.
