PR: #657: feat(documents): add family and twin surfaces [Story-2515] by @pramaan-board-bot[bot]
View PR →

Story 2515: Family + twin surfaces

Manifest T5h · Wave W5 · RFD-DOC-006. Covers ER-09, ER-34, ER-39, ER-40, ER-41, ER-42 and ER-43.

Two views, two routes

/matters/16/record/family
  → complete family tree, read waves, twins and related documents

/matters/16/record/boundary-review
  → index conflicts and uncertain anchor-level boundaries

Both routes share the Record chrome through its layout, use Link-based navigation, and export their own agentSurface. No client tab swaps these views on one URL.

Scenario proof

Scenario Visible behaviour
ER-09 The parent and all five children are linked, named, independently addressable, and carry their own read state.
ER-34 Every child remains in the tree. Wave 2 is visibly counsel-gated and can be released with the full target named.
ER-39 The index/title conflict is a review card with confidence, reason code, quotes, evidence anchors and an exact evidence link. Every one of the five detected children carries its own filing-index reconciliation record; accepted matches remain visible in the complete payload while the P-5 conflict is flagged.
ER-40 Confirmed twins carry a badge and cross-link. Candidate noisy scans ask counsel; exact matches are already confirmed. The document pool, chronology and matter brief each visibly collapse confirmed twins to one source with clear contradiction checks.
ER-41 The proposed mid-page P-4A start shows its exact review block. It has no child id or accepted start anchor, so the pages remain held in the parent until counsel decides.
ER-42 The changed-date lease is labelled Related version; both execution dates remain visible and no twin action is offered.
ER-43 Confirm and revoke update immediately, roll back on refusal, and preserve the existing counsel note, verdict history and anchor. Revocation restores separate pool, chronology and brief entries without re-extraction.

Explicit targets and optimistic writes

Every control names the object and destination, for example Confirm twin link between Annexure P-1 and COUNTER R-A, Revoke twin link between Annexure P-1 and REPLY R-1, and Release wave 2 for SOC-GOLD-1000. Confirm/revoke/release use the generated hooks with a fixture client; onMutate updates the screen immediately and onError restores the captured fixture.

Founder-law maximal disclosure

The curated tree and relationship cards are followed by an expanded, complete JSON field view. It renders the payload itself, not a hand-picked mapping, so ids, family manifest data, all detected children, every boundary confidence/anchor/receipt/reason, waves, relationship fields, twin evidence, timestamps and counsel history are visible by default.

Cutover truth

The fresh generated mirror exposes confirm, revoke and family-wave POST contracts, but no family-manifest, boundary-review or relationship-list GET contract. The browser BFF also has no live proxy for these new POSTs.

The routes are therefore hard-gated to matter 16 and inject a local fixture transport into the generated hooks. Generated response Zod parsing still runs. No request reaches a live new-path endpoint. At wave cutover, the fixture transport is removed only after generated read contracts and BFF routes exist; fixture and live payloads are never dual-served.

Files changed

23 file(s), +2670 / -13 lines

Path Role + -
messages/en.jsonConfig+97-0
messages/hi.jsonConfig+97-0
src/app/[locale]/(workspace)/matters/[matterId]/record/boundary-review/page.tsxApp route+36-0
src/app/[locale]/(workspace)/matters/[matterId]/record/family/page.tsxApp route+43-0
src/components/documents/family/boundary-review-queue.stories.tsxComponent+68-0
src/components/documents/family/boundary-review-queue.tsxComponent+157-0
src/components/documents/family/family-all-fields.stories.tsxComponent+36-0
src/components/documents/family/family-all-fields.tsxComponent+36-0
src/components/documents/family/family-surface.stories.tsxComponent+130-0
src/components/documents/family/family-surface.tsxComponent+250-0
src/components/documents/family/family-tree.stories.tsxComponent+98-0
src/components/documents/family/family-tree.tsxComponent+165-0
src/components/documents/family/presentation.tsComponent+120-0
src/components/documents/family/relationship-card.stories.tsxComponent+138-0
src/components/documents/family/relationship-card.tsxComponent+173-0
src/components/documents/family/use-family-surface.test.tsxComponent+52-0
src/components/documents/family/use-family-surface.tsComponent+101-0
src/components/documents/side-check/record-subnav.tsxComponent+16-2
src/components/shared/eyebrow.stories.tsxComponent+7-2
src/components/shared/eyebrow.tsxComponent+7-7
src/lib/documents/family-fixtures.test.tsLibrary+86-0
src/lib/documents/family-fixtures.tsLibrary+735-0
src/lib/surface-registry/route-registry.tsLibrary+22-2

Wave manifest obligations after T5h

Storybook proof

Locale contract

All interface copy and both new AgentSurfaces presence strings exist in messages/en.json and messages/hi.json. Payload values remain source data; chrome and actions are translated.