Trayectorias: how Nammu renders the right procedural roadmap for each case

Every legal process type has its own statutory sequence of stages, its own article citations, its own deadlines, its own “what happens if X does not occur.” A civil ordinario's audiencia preliminar has nothing in common procedurally with a violencia doméstica case's plazo de vigencia window. Trayectorias exists to render the correct statutory roadmap for this specific case's jurisdiction and process type — and then overlay it with actual evidence from this case's own documents to show where it really stands today. This is not a generic five-stage progress bar.

Two views over one model

The same CaseTimeline data structure feeds two deliberately distinct renderings. Keeping them separate prevents two genuinely different questions from being conflated.

The data model

Three dataclasses in timeline_model.py carry everything a builder produces:

Milestone symbols

Each milestone carries a symbol that communicates its structural role in the procedural sequence at a glance:

One builder per process type — not per jurisdiction

load_case_timeline() reads process_type from case_index.json and routes to exactly one build_*_timeline() function. This is process-type-level dispatch, not jurisdiction-level: a jurisdiction being fully classified does not guarantee every one of its process types has a template. Civil's monitorio, penal's procedimiento_abreviado and flagrancia, and contencioso's proceso_de_lesividad are all classified correctly but have no builder yet — they show a purpose-built “template missing” state, not a generic error.

Each builder is self-contained. It owns its own milestone list, article citations, and status-inference rules — grounded in a specific legal-domain review, cited in-code. There is no shared generic milestone structure that jurisdictions customize. A civil ordinario's 13 milestones and a familia violencia-doméstica case's 8 milestones do not share a single stage name or structure, because they are governed by different codes with different procedural clocks.

Phases — communicating jurisdictional change mid-process

MilestonePhase has four values. Which ones a builder uses says something legally meaningful about whether the case's jurisdiction can change mid-process.

build_ordinario_timeline() is the one builder that must handle all three possible shapes of a civil ordinario case. It picks between them explicitly: bisagra detected → emit both phases plus the gold-highlighted hinge node; non-civil jurisdiction with no bisagra yet → still show both phase templates so the mini-view roadmap is visible before a transfer; purely civil from the start → drop phase labels and stamp every milestone SINGLE.

How milestone status is inferred

Every builder inspects the pooled doc_kind set from document_index.json — the output of Smart Document Segmentation — and derives each milestone's status from which document types are present. The patterns range from simple to legally nuanced:

COMPLETED if "notificacion" in doc_kinds else UNKNOWN

COMPLETED    if a court admission resolution exists
IN_PROGRESS  if defects flagged and/or subsanación filed,
             but no court ruling yet
PENDING      if no signal at all

Milestone copy carries legal-safety guidance

The notes field on a milestone is not decorative. In several builders, it carries direct, load-bearing legal-safety instructions embedded at exactly the point in the UI where they are operationally relevant.

Date enrichment — best effort, never a status determinant

timeline_dates.py runs a separate later pass that tries to attach a real calendar date to milestones already marked reached by the status logic. It never determines whether a milestone happened — only when.

For each milestone ID, a lookup table says which doc_kind(s) to search; the first matching segment's anchor page is scanned with Spanish-date regexes covering both numeral dates (28/01/2026) and Costa Rica's canonical spelled-out judicial self-dating formula (“del veintiocho de enero de dos mil veintiséis”), including a word-to-number table for spelled-out days and years.

A date extraction failure just means a milestone shows as reached with no date — never a reason to downgrade or hide a status the doc_kind evidence already established.

Seven distinct empty states

Trayectorias deliberately does not collapse every “nothing visible” situation into one generic empty state. The reason a case has nothing to show is itself useful information, and conflating the reasons would mislead the lawyer about what is actually going on.

Guiding principles