> 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/phases/phase_28/session_03_calibration_version_and_confidence_dampener.md).

# Session 03: Calibration Version Stamp And Confidence Dampener

**Session ID**: `phase28-session03-calibration-version-and-confidence-dampener` **Status**: Complete **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Stamp a scoring calibration version into snapshots and prediction records, have movement and retro layers flag (not suppress) cross-version comparisons, and add a bounded small-sample confidence dampener that publishes a confidence value the UI can display. These two cheap items protect the entire history layer from every scoring change this phase introduces.

***

## Source Mapping (from the Trends-Finderz improvement map, items 7.2 and 2.3)

### Scoring calibration version stamp (item 7.2)

* **Trends-finderz:** every snapshot records `scoringCalibrationVersion = "trend-finder-scoring-v2"`, so any consumer comparing snapshots across a scoring change can detect the discontinuity.
  * `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/lib/scoring/trend-snapshots.ts` (line \~46)
* **Trend Finder today:** snapshots, movement deltas, historical context, and retro grading all compare scores across runs with no record of which scoring formula produced each score. A weight change in `scripts/lib/ai-runtime/scoring.ts` silently turns every next-run movement status into an artifact ("rising" because the formula changed), and retro grades straddling the change are quietly wrong.
* **Improvement:** export a `SCORING_VERSION` constant from `scoring.ts`, stamp it into snapshots and prediction records, and have movement analysis and retro grading flag (not suppress) cross-version comparisons with an explicit provenance note.
* **Implement in:** `scripts/lib/ai-runtime/scoring.ts`, `scripts/lib/ai-runtime/snapshots.ts`, `scripts/lib/ai-runtime/predictions.ts`, comparison guards in `scripts/lib/ai-runtime/movement-analyst.ts` and `scripts/lib/ai-runtime/retros.ts`; optional label in `src/extensions/trend-finder/schema.ts`.
* **Note:** land this first within the session -- it protects every later scoring change in this phase (noise downrank, lifecycle multiplier, aging, saturation refinement) from being misread as movement.

### Small-sample confidence dampener (item 2.3)

* **Trends-finderz:** the overall trend score is dampened by sample confidence -- `confidenceDampener(clampScore(raw), sampleConfidence, 0.62)` pulls scores toward a floor when evidence counts are thin.
  * `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/lib/scoring/trend-score.ts`
  * `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/lib/scoring/score-utils.ts`
* **Trend Finder today:** zero-evidence topics zero out three factors (`docs/extensions/trend-finder-scoring.md`), and source-local baselines have explicit low-sample states, but a topic with 2 thin evidence rows and a topic with 40 strong rows can produce similar weighted sums with no global confidence discount.
* **Reconciliation:** Phase 27 Session 01 already shipped banded confidence labels; this session adds the numeric dampener and the confidence value those bands can render, not a new label vocabulary.
* **Improvement:** derive a 0-100 sample-confidence value (evidence count, distinct sources, scoring-evidence share) and apply a bounded dampener to the overall score, publishing the confidence value so the UI can show it.
* **Implement in:** `scripts/lib/ai-runtime/scoring.ts`; field in `src/extensions/trend-finder/schema.ts`; display in `src/extensions/trend-finder/components/score-breakdown.tsx`.

***

## Scope

### In Scope (MVP)

* `SCORING_VERSION` constant exported from `scoring.ts`
* Version stamped into snapshot and prediction records
* Cross-version comparison flags (with provenance note) in movement and retro layers -- flagged, never suppressed
* 0-100 sample-confidence derivation (evidence count, distinct sources, scoring-evidence share)
* Bounded confidence dampener applied to the overall score, recorded so the adjustment is visible (pairs with Session 06 named contributions)
* Confidence value published and shown in the score breakdown
* Tests: version stamping, cross-version flagging, dampener bounds, low-sample vs strong-sample behavior, legacy parsing

### Out of Scope

* Rewriting the six-factor weights
* Migrating historical snapshots that predate the stamp (treated as `unknown`-version and flagged)
* The named-contribution breakdown convention itself (Session 06; this session records the dampener delta in a forward-compatible way)

***

## Prerequisites

* [x] Phase 27 baseline present (snapshots, predictions, movement, retro layers current)

***

## Deliverables

1. `SCORING_VERSION` constant and stamps in snapshots and predictions
2. Cross-version comparison flags with provenance notes in movement and retro
3. Sample-confidence derivation and bounded score dampener
4. Confidence value in the schema and score-breakdown UI
5. Tests for stamping, cross-version flagging, dampener behavior, and legacy parsing

***

## Success Criteria

* [x] Every new snapshot and prediction records the scoring version
* [x] Movement and retro comparisons across a version change are flagged with a provenance note, not silently treated as movement
* [x] Thin-evidence topics are pulled toward a floor by a bounded dampener; strong-evidence topics are minimally affected
* [x] The published confidence value renders in the score breakdown
* [x] Pre-stamp history reads as `unknown`-version and is handled, not crashed
* [x] Existing scoring, movement, and retro tests pass


---

# 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/phases/phase_28/session_03_calibration_version_and_confidence_dampener.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.