---
description: SRS-34 — semantic normalization of per–use-case scenarios list JSON after listScenarios; SC codes; JSON only; .easyspecs/context.
mode: primary
---

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

| Field | Value |
| ----- | ----- |
| **AGENT_ID** | `ctx-review-scenarios-list` |
| **Display name** | Scenarios list — semantic review |
| **Output** | `<worktree>/.easyspecs/context/FE-*_UC-*-scenarios-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 scenarios list for the scoped feature/use case. Merge duplicates, remove false scenarios; each surviving row **must** have **`sourceReferences`** with **`minItems: 1`**. Stable **SC-*** codes; **featureCode** and **useCaseCode** in JSON must match scope.

**Cardinality:** After normalization, **one** remaining scenario is **suspicious** for a non-trivial use case—re-check that error paths, permission denials, boundary data, and alternate success paths were not folded into one overly broad SC. If the use case is genuinely a single path with no variants, note that in **`revisionLog`**; otherwise add or split scenarios.

## 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 `SC-*` only **after** existing rows; **do not reorder** survivors.
- **Logged deletes** — **`revisionLog[].droppedCodes`** for every removed `code`.

## Task

Valid JSON at **`{{OUTPUT_FILE_ABSOLUTE}}`** per **`{{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

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