> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase27-session01-brief-movement-groups-and-calibration-metrics/spec.md).

# Session Specification

**Session ID**: `phase27-session01-brief-movement-groups-and-calibration-metrics` **Phase**: 27 - Trend Finder Alpha Radar Adoption **Status**: Not Started **Created**: 2026-06-12

***

## 1. Session Overview

This session begins Phase 27 by making already-generated Trend Finder movement and retro data visible in the creator-facing Brief surfaces. Trend Finder already stores topic movement status, movement analyses, prediction rows, and retro rows; the gap is that Brief and Static Brief underuse that information and do not publish aggregate accountability metrics.

The session ports the useful Alpha Radar presentation concepts without adopting its weaker data rigor. It adds movement-grouped Brief sections, an explicit today's pick with a selection reason, consistent confidence band labels, and a bounded calibration summary with outcome counts, hit rate, and a Brier-style score over resolved retro records.

All work stays additive and browser-safe. No new source adapters, AI calls, raw archives, prompts, provider responses, private paths, or local triage notes enter browser state or exported static reports.

***

## 2. Objectives

1. Add a bounded additive calibration object to `predictionRetroSummary`.
2. Compute outcome counts, resolved hit rate, and Brier-style calibration from existing retro records with explicit unavailable states.
3. Add shared view-model helpers for confidence bands, today's pick copy, movement groups, and calibration presentation.
4. Render the new sections in the live Brief view and Static Brief export with focused regression tests.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase26-session09-documentation-validation-release` - closes the Knowledge Graph Shared Brain Port baseline required by Phase 27.

### Required Tools/Knowledge

* Bun 1.3.14 for package scripts and Vitest.
* React 19, TanStack Start, Tailwind CSS 4, and existing local UI patterns.
* Zod additive defaults for browser payload compatibility.
* Existing Trend Finder retro, movement, static export, and visibility helpers.

### Environment Requirements

* Repository rooted at `/home/aiwithapex/projects/aios`.
* Phase 27 PRD stubs present under `.spec_system/PRD/phase_27/`.
* No live retro archive is required for tests; fixture and empty-state coverage must exercise both archive-present and archive-missing behavior.

***

## 4. Scope

### In Scope (MVP)

* Trend Finder operator can scan Brief by moved-up, cooled, and emerging topics using existing `movementStatus` and `movementAnalyses` fields.
* Trend Finder operator can see a today's pick with a bounded selection reason based on rank, movement, confidence band, source count, and creator angle or lens-fit copy when available.
* Trend Finder operator sees confidence as a consistent low/medium/high band across card, Brief, and Static Brief surfaces.
* Trend Finder operator sees prediction accountability through outcome counts, resolved hit rate, and Brier-style score in live Brief and Static Brief.
* Browser payload consumers keep parsing legacy payloads that omit the new calibration object.
* Static Brief export projects the new sections through its projection layer and retains the existing privacy scan.

### Out of Scope (Deferred)

* Dated predictions and Story Log - Reason: planned for Session 08.
* New movement math - Reason: this session renders existing movement fields.
* New AI, source, or enrichment calls - Reason: this is a Tier 1 visibility and deterministic-derive session.
* Source adapters or YouTube thumbnails - Reason: compliance-first source work remains deferred out of Phase 27 Session 01.
* Any mutation of generated Watchlist or browser-local triage state - Reason: watching/pin state is Session 03.

***

## 5. Technical Approach

### Architecture

Keep the data path additive. Extend `PredictionRetroSummarySchema` with a small calibration summary default, then produce it from existing retro records where `predictionRetroSummary` is assembled. Add reusable view-model helpers for confidence and Brief grouping so live UI, card UI, and static export share labels and tones instead of duplicating display rules.

Static Brief must continue to be projection-first. `static-brief-export.ts` should project movement groups, today's pick, confidence bands, and calibration rows into a bounded report shape. `static-brief-renderer.ts` should only render that projected report and continue to pass privacy scanning.

### Design Patterns

* Additive schema defaults: Preserve old generated payloads and fixtures.
* Project before rendering: Keep raw Trend Finder payload reads out of static HTML rendering.
* Script-only runtime boundary: Retro aggregation stays in `scripts/lib/` and browser code consumes sanitized fields.
* Explicit unavailable states: Calibration renders "Unavailable" rather than fake zeros when no resolved retros exist.
* Stable deterministic ordering: Movement groups keep rank order within each group and use existing score tie-breakers.

### Technology Stack

* TypeScript 6.0.3
* React 19.2.0
* Zod 4.4.3
* Vitest 4.1.6
* Playwright 1.60.0 for existing Static Brief e2e coverage if needed
* Bun 1.3.14

***

## 6. Deliverables

### Files to Create

| File | Purpose                                                                        | Est. Lines |
| ---- | ------------------------------------------------------------------------------ | ---------- |
| None | This session modifies existing Trend Finder contracts, projections, and tests. | \~0        |

### Files to Modify

| File                                                                      | Changes                                                                           | Est. Lines |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------- |
| `src/extensions/trend-finder/schema.ts`                                   | Add calibration schema/defaults under prediction retro summary.                   | \~80       |
| `scripts/lib/ai-runtime/retros.ts`                                        | Add outcome aggregate and Brier-style helper.                                     | \~120      |
| `scripts/extensions/trend-finder/collector.ts`                            | Populate calibration summary for live collection.                                 | \~30       |
| `scripts/lib/ai-runtime/backtests.ts`                                     | Populate calibration summary for backtest publish path.                           | \~25       |
| `scripts/trend-finder-replay-backhistory.ts`                              | Populate calibration summary for replay path.                                     | \~25       |
| `src/extensions/trend-finder/view-model.ts`                               | Add confidence bands, movement groups, today's pick, and calibration view models. | \~180      |
| `src/extensions/trend-finder/components/trend-card.tsx`                   | Render confidence band labels consistently.                                       | \~30       |
| `src/extensions/trend-finder/views/brief-view.tsx`                        | Render today's pick, movement groups, and calibration panel.                      | \~220      |
| `scripts/extensions/trend-finder/static-brief-export.ts`                  | Project new Brief sections into the static report shape.                          | \~180      |
| `scripts/extensions/trend-finder/static-brief-renderer.ts`                | Render projected movement groups and calibration summary.                         | \~190      |
| `src/extensions/trend-finder/fixtures.ts`                                 | Add fixture coverage for new summary defaults and filled state.                   | \~80       |
| `scripts/lib/ai-runtime/__tests__/retros.test.ts`                         | Cover aggregate and Brier-style math.                                             | \~120      |
| `src/extensions/trend-finder/__tests__/view-model.test.ts`                | Cover confidence bands, grouping, today's pick, and calibration view models.      | \~120      |
| `src/lib/__tests__/trend-finder-schema.test.ts`                           | Cover legacy payload parsing with omitted calibration.                            | \~70       |
| `scripts/extensions/trend-finder/__tests__/static-brief-export.test.ts`   | Cover projection and privacy-safe report shape.                                   | \~100      |
| `scripts/extensions/trend-finder/__tests__/static-brief-renderer.test.ts` | Cover rendered section text and empty states.                                     | \~80       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Brief groups visible topics into moved-up, cooled, and emerging sections using existing payload data only.
* [ ] Today's pick renders a bounded selection reason and does not invent unsupported metrics.
* [ ] Confidence bands render consistently across TrendCard, Brief, and Static Brief rows.
* [ ] Calibration summary includes outcome counts, resolved count, hit rate, Brier-style score, generated timestamp, and explicit unavailable state.
* [ ] Static Brief includes the new sections through projection and retains public-link and privacy filtering.
* [ ] Legacy payloads that omit calibration still parse with safe defaults.

### Testing Requirements

* [ ] Unit tests cover retro aggregate math including hit, partial, miss, and pending outcomes.
* [ ] Unit tests cover confidence band thresholds and movement grouping order.
* [ ] Schema tests cover default parsing for legacy payloads.
* [ ] Static Brief export and renderer tests cover projected sections and empty states.
* [ ] Focused tests pass before full validation is attempted.

### Non-Functional Requirements

* [ ] No new source calls, AI calls, third-party transfers, or browser-visible raw archives are introduced.
* [ ] New arrays and report sections remain bounded under the existing Trend Finder payload and static export limits.
* [ ] Browser and static report copy is explicit when calibration is unavailable.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] `bun run test` passes or failures are documented before validation.
* [ ] `bun run typecheck` and `bun run typecheck:scripts` pass or failures are documented before validation.

***

## 8. Implementation Notes

### Key Considerations

* Treat `pending` retros as tracking records, not resolved accuracy records.
* A deterministic Brier-style score can use resolved outcome targets where hit is 1, partial is 0.5, and miss is 0, with the deterministic prediction probability treated as 1 for the expected outcome. Document the unavailable state when there are no resolved rows.
* Keep calibration labels bounded and sanitized in the view-model rather than rendering raw enum values.
* Static Brief rendering should consume projected report fields only.

### Potential Challenges

* TypeScript fallout from adding a required schema field: Mitigate with a default constant and helper reused by collector, backtest, replay, fixtures, and snapshot tests.
* Existing fixtures may hide legacy parsing bugs: Add one explicit legacy payload test that omits the calibration object.
* Brier terminology can imply precision the data does not have: Label it as a Brier-style calibration score and include an unavailable state below sample threshold.
* Brief density can grow too large: Keep sections collapsible or compact and preserve current visibility controls.

### Relevant Considerations

* \[P02] **Extension payloads and demo labels stay bounded**: New report fields stay bounded, additive, and explicitly unavailable when source data is absent.
* \[P15] **Aggregate collection must stay budgeted**: This session adds no new collection or analyst calls.
* \[P24] **Browser-safe export and triage boundaries**: Static Brief must not include private archives, local triage notes, prompts, logs, or raw payloads.
* \[P24] **Project before rendering**: Static Brief gets new sections only via `static-brief-export.ts`.
* \[P24] **Additive defaults keep legacy payloads alive**: The calibration object must not break existing generated payloads or fixtures.
* \[P24] **Deterministic ordering helps dense triage**: Movement groups preserve ranked ordering with explicit fallbacks.
* \[P05] **Script-only runtime boundary**: Retro aggregation stays in script code and browser surfaces consume validated summary fields only.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Legacy payloads without calibration fields must not crash UI, static export, or snapshots.
* Empty retro archives must render clear unavailable states instead of fake accuracy metrics.
* Static export must continue excluding private paths, raw logs, provider responses, prompts, and local cache internals.

***

## 9. Testing Strategy

### Unit Tests

* `scripts/lib/ai-runtime/__tests__/retros.test.ts`: outcome counts, resolved hit rate, pending exclusion, Brier-style score, empty state.
* `src/extensions/trend-finder/__tests__/view-model.test.ts`: confidence band thresholds, movement grouping, today's pick reason, calibration labels.
* `src/lib/__tests__/trend-finder-schema.test.ts`: additive default parsing.
* `scripts/extensions/trend-finder/__tests__/static-brief-export.test.ts`: projected report shape and privacy scan.
* `scripts/extensions/trend-finder/__tests__/static-brief-renderer.test.ts`: rendered sections and empty/unavailable states.

### Integration Tests

* Run existing collector and static export tests touched by `predictionRetroSummary` construction.
* Run existing Static Brief e2e only if renderer/export changes affect page structure or selectors.

### Manual Testing

* Open the Brief route with fixture data and confirm today's pick, movement groups, confidence bands, and calibration sections fit without overlap.
* Generate a Static Brief export and inspect that movement and calibration sections render while private-boundary footer and privacy scan remain intact.

### Edge Cases

* No topics.
* Topics with only `steady` movement.
* Retro archive missing.
* Retro archive present with only pending rows.
* Partial outcomes mixed with hit and miss rows.
* Legacy payload without the new calibration object.
* Hidden Brief items through visibility controls.

***

## 10. Dependencies

### External Libraries

* No new external libraries.

### Other Sessions

* **Depends on**: `phase26-session09-documentation-validation-release`
* **Depended by**: `phase27-session02-deterministic-derived-signals-and-risk-flags`, `phase27-session03-data-driven-radar-aliases-and-watching-state`, `phase27-session08-dated-predictions-and-story-log`

***

## Next Steps

Run the implement workflow step to begin AI-led implementation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase27-session01-brief-movement-groups-and-calibration-metrics/spec.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.