| 18 | `PROSTHESIS_CATEGORY` + `PROSTHESIS_SUBCATEGORY` in `CatalogEntityKind`; migration; seed fa/en/nl translations | `dyolink` | ⬜ | §5, decision 47. **Must land before item 9** |
| 19 | Unresolved items carry `assignmentIndex`; a picked chip inherits that assignment's jobs | `dyolink` | ⬜ | §6, decision 50. Without it the quadrant chip is dead on a prosthesis detail |
### Blocking gap 1 — `missing_constraint` (dyolink)
**Summary:** The prompt must present prosthesis categories and subcategories so the model can
return `crown` for "روکش", but no localized label for a category or subcategory exists anywhere
the backend can read. `CatalogEntityKind` has only TREATMENT_TYPE / PROSTHESIS_TYPE /
LAB_WORKFLOW_STEP, and the only category labels in the repo are frontend message keys
(`category_crown`, `sub_night_guard`) plus a hardcoded single-locale map in a dev export script.
**Spec quotes:**
> **The prosthesis list is no longer flat.** `buildCatalog` already receives `category`, `subcategory`, `chartRegion` and `stackGroup` from `ProsthesisCatalogService` and throws all four away. It now passes them through, so the prompt presents the catalog as the tree it is and marks which codes are jaw-level. Still no catalog knowledge hardcoded in the prompt — the shape comes from the data.
> Treatment types and prosthesis types come from `CatalogLabelService` in the actor's locale, so the model sees "پروتز" and "زیرکونیا مونولیتیک" as the spoken forms of `prosthesis` and `monolithic_zirconia` rather than being asked to translate. Catalog entities store a stable `code` and no label — never hardcode a label.
> "روکش" is *crown* — a category with nine leaves, not a material. The model returns the category code it actually heard rather than guessing `pfm_crown`, and the review sheet offers the leaves as chips (§7).
**Why blocking:** Work item 9 ("Prompt: present the catalog as a tree") cannot be built.
`ProsthesisCatalogService.list()` returns `category` and `subcategory` as bare codes with no label
(prosthesis-catalog.service.ts:82-95), and `CatalogLabelService` cannot resolve them because
`CatalogEntityKind` has no category kind (schema.prisma:331-335). The three ways out have
different costs and one breaks an explicit repo rule, so a builder cannot choose: (a) add
PROSTHESIS_CATEGORY / PROSTHESIS_SUBCATEGORY to the enum plus a migration and seeded translations
— a schema change the spec never mentions; (b) hardcode a fa/en/nl label map in the backend, which
the spec and CLAUDE.md both forbid; (c) send bare codes only, which makes the whole category
feature unmeasured on the weakest locale.
**Question:** Where do the localized labels for the 7 prosthesis categories and 5 subcategories
come from for the extraction prompt: a new `CatalogEntityKind` (PROSTHESIS_CATEGORY /
PROSTHESIS_SUBCATEGORY) with a migration and seeded `CatalogTranslation` rows, or bare codes with
no labels in the prompt?
**Suggested spec change:** Add to §5: "Category and subcategory labels have no backend source
today — `CatalogEntityKind` covers only TREATMENT_TYPE, PROSTHESIS_TYPE and LAB_WORKFLOW_STEP, and
`category_*` / `sub_*` exist only in `frontend/messages/*.json`. Add `PROSTHESIS_CATEGORY` and
`PROSTHESIS_SUBCATEGORY` to `CatalogEntityKind` (one migration), seed their fa/en/nl translations
from the existing message keys, and resolve them through `CatalogLabelService` like every other
**Note 1 — `ambiguity` (dyolink).** An unresolved item carries only `spoken`, `reason` and
`candidates`, with no link back to the assignment it came from. On a prosthesis detail a
`tooth_missing_quadrant` chip therefore resolves to a tooth with no job, which the "tooth with no
job is named and left out" rule then discards — so tapping the chip does nothing.
> **A single digit alone is never resolved.** "دندون دو" names four teeth. It is reported as `tooth_missing_quadrant` **with the candidate codes attached**
> **A tooth with no job is named and left out.**
> Picking one folds the choice into the result, so an under-specified item is one tap from resolved instead of a dead end.
*Why not blocking:* a builder can add an assignment reference to the unresolved item. But §6's
reason table reads as a complete contract and its "Carries" column names only `candidates`, so a
builder following it literally ships a dead chip on exactly the prosthesis flow §12 asks them to
test.
*Question:* Should `VoiceUnresolvedItem` gain an assignment reference (for example
`assignmentIndex`) so a chosen quadrant chip inherits that assignment's job stack?
*Suggested spec change:* In §6's reason table, add: "`tooth_missing_quadrant` and
`arch_not_spoken` also carry the index of the assignment they came from, so a picked chip inherits
that assignment's `types[]` rather than becoming a jobless tooth."
**Note 2 — `ambiguity` (dyolink).** "The resolver confirms [jaw vs tooth] against the
`chartRegion` of the assignment's codes" is undefined when `types[]` holds a category whose leaves
have mixed regions. `removable` is exactly that: `complete_denture` and `overdenture` are
`chartRegion: 'arch'`, `partial_denture` is `'crown'`.
> A target that names an arch and no position is a jaw, and the resolver confirms that against the `chartRegion` of the assignment's codes.
> `partial_denture` — a `removable` code that is nonetheless assigned per tooth — already ships with `chartRegion: 'crown'` in `catalog-seed-data.ts`, so the exception needs no special case either.
> A code whose region contradicts its target is reported, never coerced.
*Why not blocking:* deferring the region check until the ambiguity chip is picked is a reasonable
default. Worth stating so the builder does not emit `code_not_valid_for_target` for a category that
has not been narrowed yet.
*Question:* When `types[]` holds a category whose leaves span both `crown` and `arch` regions (only
`removable` today), is the region check deferred until the clinician picks a leaf chip?
*Suggested spec change:* In §5 under "A target is a tooth or a jaw": "When `types[]` holds a
category whose leaves have more than one `chartRegion`, the region check is deferred — the item
resolves to `prosthesis_type_ambiguous` and the region is confirmed against the leaf the clinician
**Note 4 — `contradiction` (dyolink).** §11 item 13 says v1 ships with "no availability endpoint",
but §4 requires the frontend to learn enabled locales from the API, and `GET /voice/availability`
exists and is what `voiceForEditor` reads today.
> ~~**Availability API**~~ — **resolved for v1:** voice ships **open to everyone** with a configured locale profile. No plan check, no availability endpoint.
> The frontend must learn which locales are enabled **from the API**, not from a `NEXT_PUBLIC_*` var
*Why not blocking:* work item 2 ("`voiceForEditor` also checks `isMediaRecorderSupported()`")
presupposes `voiceAvailability` stays, so the working reading is obvious. The stale line just needs
correcting so nobody deletes a live endpoint.
*Question:* Confirm the availability endpoint stays in v1 and only the plan check is deferred?
*Suggested spec change:* Reword item 13 to "no plan check; the availability endpoint ships and
reports configured locales and `maxRecordingMs` only."
(all paths relative to `/Users/aminmsvi/PersonalProjects/dyolink`)
### How to resume
Close the gaps in the spec, then re-run. Pass `gapNote` describing what you changed, or the
analyst replays this same verdict from cache.
---
## 2026-09-07 — Gaps closed, ready to re-run
All five findings are now answered in the spec. Nothing was built in the halted run, so there is
no code to revisit.
| Finding | Resolution | Spec |
|---|---|---|
| **Blocking** — no backend source for category labels | Add `PROSTHESIS_CATEGORY` + `PROSTHESIS_SUBCATEGORY` to `CatalogEntityKind`, one migration, seed fa/en/nl from the existing `prosthesis.category_*` / `sub_*` keys, resolve via `CatalogLabelService`. Frontend keeps its own keys — migrating it is out of scope | §5, decisions 47–48 |
| Note 1 — chip with no assignment link | Unresolved items raised inside an assignment carry `assignmentIndex`; a picked chip inherits that assignment's `types[]` | §6, decision 50 |
| Note 2 — mixed-region category | `removable` defers its region check to the picked leaf; never `code_not_valid_for_target` while still a category | §5, decision 49 |
| Note 3 — wrong endpoint path in §3 | Corrected to `POST /voice/extract`, with the `body-parsers.ts` coupling called out. No work item moves the route | §3 |
| Note 4 — availability endpoint contradiction | §11 item 13 corrected: the endpoint exists, only the plan check is deferred | §11 |
| Note 5 — disjointness counts | Verified independently: **42** leaf codes (the surveyor's 41 missed `screw_retained`, a multi-line `implant(` call) and **5** subcategories (the spec said 4, missing `night_guard`). The test now asserts against the live catalog, not a written count | §5, §12 |
Referee relays: 0. Gate repairs: 0. Neither phase was reached.
