> 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/prd_phase_28.md).

# PRD Phase 28: Trend Finder Trends-Finderz Adoption

**Status**: Complete **Sessions**: 15 (initial estimate) **Estimated Duration**: 16-22 days

**Progress**: 15/15 sessions (100%)

***

## Overview

Phase 28 adopts the objective improvements mapped from the Trends-Finderz reference project into the Trend Finder extension. The mapping was captured on 2026-06-12 in `docs/ongoing-projects/trends-finderz.md`; this phase PRD and its session stubs fold in the complete mapping with full source URLs so that file can be deleted in the closeout session without losing detail.

Trends-finderz is a runnable product, not a static demo: a Next.js App Router app with PostgreSQL/Drizzle persistence, real source connectors, a fully deterministic scoring pipeline (no AI runtime anywhere), scheduled scans, and QA/admin surfaces. Its architecture rule is `scan -> normalize -> store raw signals -> cluster topics -> calculate scores -> save snapshots -> product pages read snapshots`. Because it ships complete deterministic implementations (not just a data contract), it is an excellent quarry for Trend Finder's deterministic fallback path and zero-cost derived signals. The mapping is grounded in the artifacts below; every path was verified against the working tree on 2026-06-12 and re-verified on 2026-06-13.

| Artifact             | Path                                                                              | What It Proves                                                        |
| -------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| Project overview     | `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/README.md`                | Feature list, access model, retention policy, scheduled scan design.  |
| Data model           | `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/drizzle/migrations/*.sql` | Signal dedup columns, canonical topics, saved-trend baselines, locks. |
| Signal quality layer | `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/lib/signals/`             | URL normalization, content hashes, fingerprints, quality scores.      |
| Scoring layer        | `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/lib/scoring/`             | Trend score, saturation, visibility gate, calibration version.        |
| Product QA layer     | `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/lib/product/`             | Aging, research calibration, evidence/action consistency checks.      |
| Trend surfaces       | `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/lib/trends/`              | Lifecycle, action priority, watchlist deltas, daily brief, reports.   |
| Scan orchestration   | `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/lib/scan/`                | Scan modes, connector readiness, keyword coverage, reliability QA.    |
| Keyword config       | `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/lib/config/`              | Category keyword packs, scan modes, per-source keyword caps.          |
| Search               | `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/lib/search/`              | Dependency-free hash embeddings and hybrid ranking.                   |
| Source connectors    | `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/lib/sources/`             | Direct first-party API adapters (arXiv, GitHub, HN Algolia, RSS).     |
| Cron/retention       | `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/lib/cron/`                | TTL DB locks and retention cleanup with preserved-table policy.       |
| UI components        | `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/components/`              | Scan health, action queue, command palette, suppressed-noise views.   |

Trend Finder's current behavior is documented in `docs/extensions/trend-finder-*.md` and implemented under `src/extensions/trend-finder/`, `scripts/extensions/trend-finder/`, and `scripts/lib/ai-runtime/`.

"Objective improvement" means: a capability trends-finderz demonstrably implements (running code, not a mock) that Trend Finder lacks or implements more weakly, and that can be adopted without breaking Trend Finder invariants. Port the algorithms and product concepts, never the persistence or hosting shape: trends-finderz is a hosted multi-page app with a server database, access-code auth, and CI-scheduled scans, while Trend Finder is a compile-time registered local extension with a browser-safe generated payload and private file caches. Durable storage direction is owned by `docs/ongoing-projects/sqlite-observation-store-transition-plan.md`.

### Reconciliation With Phase 27 (Read Before Building)

The trends-finderz mapping was captured 2026-06-12, before Phase 27 Sessions 05-12 completed (2026-06-13). Phase 27 shipped several capabilities the mapping still describes as gaps, and deleted the mapping's companion file (`docs/ongoing-projects/alpha-radar.md`) in its closeout. Each affected session stub carries the reconciled framing; the summary is:

| Mapping item                               | Phase 27 reality (do not re-implement)                                                                               | Phase 28 adopts                                                                                          |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| 3.1 lifecycle classifier                   | Session 06 shipped a lifecycle taxonomy (`unknown/whisper/builder/creator/saturated`) wired to cards/Workbench/radar | The residual freshness-from-age decay curve as an aging input (S05), not a competing maturity vocabulary |
| 3.3 saturation estimate                    | Session 02 shipped deterministic saturation (source share, evidence-vs-peak, recurrence)                             | Refinement only: diffusion, mainstream-term density, single-source/GitHub-dominance discount (S05)       |
| 4.4 research-only flag                     | Session 02 shipped a risk-flag set (`single-source-signal`, `stale-evidence`, ...)                                   | A new `research-only` flag that extends that existing set (S07)                                          |
| 8.2 embeddings (theme/fallback clustering) | Session 11 shipped theme rollups + an investigate-only embedding-clustering ADR (no dependency shipped)              | Ships the dependency-free feature-hash embeddings the ADR deferred; resolves that decision (S11)         |
| 2.2 early-hidden-gem rescue                | Session 02 shipped a continuous hidden-gem score; `HIDDEN_GEM_CRITERIA` lives in `scripts/lib/ai-runtime/scoring.ts` | The visibility-gate rescue rule, tested against the existing gem score/criteria (S04)                    |
| 2.3 confidence dampener                    | Session 01 shipped banded confidence labels                                                                          | The numeric dampener those bands can display (S03)                                                       |
| Section 10.4 cross-references (sparkline,  | All six already shipped in Phase 27 (S04 sparklines, S03 aliases/radar/watching, S01 movement Brief, S02 gem score)  | Nothing -- recorded under "Already Shipped In Phase 27, No Action" below                                 |
| aliases, movement Brief, gem score, radar) |                                                                                                                      |                                                                                                          |

All `alpha-radar.md` section references in the mapping point at a deleted file; the stubs translate each to the Phase 27 session that shipped it.

The trends-finderz lifecycle classifier details are still retained for calibration even though the vocabulary is not ported. Its `computeTrendLifecycle()` reference classifies topics as `Emerging`, `Accelerating`, `Peaking`, `Cooling`, `Stale`, or `Dormant` from latest-signal age, cross-window momentum, velocity, and saturation; emits a one-line summary and `stalenessRisk` band; and uses thresholds such as `Dormant` above roughly 336 hours. Sessions 05-06 use those formulas as aging and multiplier calibration fixtures, while preserving the Phase 27 lifecycle taxonomy as the only Trend Finder maturity vocabulary.

### Trend Finder Invariants (Every Session Must Respect)

* Browser-safe payload boundary (`docs/extensions/trend-finder-pipeline.md`): no raw prompts, provider responses, logs, billing, or private paths. Hashes of public URLs are fine; raw private paths and full URLs are not.
* Deterministic fallback for every AI stage (`docs/extensions/trend-finder-runtime-and-provenance.md`). Trends-finderz is templates-only, which makes it an ideal source for fallback logic; its composed narrative strings keep `fallback`/derived provenance when ported.
* Compliance-gated sources: collection-path changes require updating the matching `docs/sources/source-compliance-<source>.md` first (`docs/extensions/README_docs-extensions.md`, `docs/sources/apify-source-onboarding.md`).
* Validators reject invented metrics, dates, URLs, and sources (`scripts/lib/ai-runtime/trend-analyst.ts`). All trends-finderz signals are derived from observed data, so conflict is rare -- but ported composed strings must keep derived/fallback provenance labels.
* Numeric constants in trends-finderz (weights, half-lives, thresholds) are calibrated against its metric scales. Treat them as starting points needing recalibration against Trend Finder's normalized factors, not portable truths.

### Where Trend Finder Is Already Ahead (Do Not Regress)

Several trends-finderz mechanisms are the weaker version; sessions must not regress these while porting:

| Area               | Trend Finder advantage                                                                                                                               |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| AI + fallback      | Full analyst runtime with validation and deterministic fallback (`scripts/lib/ai-runtime/`); trends-finderz is templates-only.                       |
| Provenance         | Live/fixture/degraded/blocked/fallback labels on every surface; trends-finderz has no provenance concept.                                            |
| Compliance         | Reviewed per-source compliance docs, compliance gate, placeholder-Actor blocking; trends-finderz fetches without a gate.                             |
| Baseline math      | Median peer-entity baselines with placement exclusion and low-sample states (`scripts/extensions/trend-finder/source-local-signals.ts`).             |
| Spend visibility   | Per-source spend accounting with estimate labels (`scripts/extensions/trend-finder/spend-accounting.ts`); trends-finderz has no cost model.          |
| Prediction loop    | Dated predictions, retro grading, backtests (`scripts/lib/ai-runtime/predictions.ts`, `retros.ts`, `backtests.ts`); trends-finderz predicts nothing. |
| Run proof          | Engine Replay sanitized trace + Reference mode; trends-finderz admin pages show config, not run evidence.                                            |
| Topic identity     | Canonical IDs, alias resolution, movement, 84-day history, 12-week summaries (`scripts/lib/ai-runtime/topic-identity.ts`).                           |
| Enrichment caching | Atomic enrichment cache with prune + hit/miss accounting (`scripts/extensions/trend-finder/enrichment-cache.ts`).                                    |
| Run overlap        | Scheduler lock + explicit browser overlap states already exist; its TTL DB lock solves a hosted problem Trend Finder does not have.                  |

### Already Shipped In Phase 27, No Action

The mapping's Section 10.4 table lists features that confirm gaps the Alpha Radar mapping already catalogued. Phase 27 shipped all of them; Phase 28 takes no action on these:

| Trends-finderz feature                                   | Shipped in Phase 27                                       |
| -------------------------------------------------------- | --------------------------------------------------------- |
| `TrendTimeline.tsx` day-bucketed series                  | Session 04 (daily series + sparklines)                    |
| `topics.aliases` columns + alias rendering on cards      | Session 03 (bounded alias chips)                          |
| Daily Brief "What changed" narrative + moved\_up/down    | Session 01 (movement-grouped Brief)                       |
| `hidden-gem-score.ts` continuous gem score               | Session 02 (continuous hidden-gem score)                  |
| Radar/quadrant dashboard visuals (`TrendRadar.tsx`)      | Session 03 (data-driven radar projection)                 |
| `cluster-topics.ts` + `topic-identity.ts` canonical keys | Pre-existing (`scripts/lib/ai-runtime/topic-identity.ts`) |

### Explicit Non-Goals (Not Worth Porting)

* **PostgreSQL/Neon/Drizzle persistence and pgvector** -- durable-store direction is owned by `docs/ongoing-projects/sqlite-observation-store-transition-plan.md`; Session 11's hash embeddings work without any vector database.
* **Access-code/admin auth, signed cookies, proxy gate** (`proxy.ts`, `lib/access/`) -- Trend Finder is loopback-local with no public surface.
* **Public landing page, demo explainer, visit counter, PDF explainer export** -- marketing surfaces for a hosted demo.
* **GitHub Actions cron workflows** (`.github/workflows/trend-finder-hourly-scan.yml`, `-daily-cleanup.yml`) -- the scoped scheduler with reviewed cadences covers this locally.
* **Window-keyed snapshot triplication (24h/7d/30d rows per scan)** -- run-based snapshots + historical context derive the same answers; revisit only inside the SQLite plan.
* **Beta/deployment-readiness checklists** (`components/admin/BetaReadinessView.tsx`, `DeploymentReadinessView.tsx`) -- ship-gating for a hosted product; Trend Finder's equivalent is its test suites and Engine Replay.
* **Server-composed PDF export** (`lib/trends/daily-brief-server-pdf.ts`) -- possible without new dependencies but low local value; Session 12 ships Markdown copy and defers PDF unless a concrete need appears.

### Deferred: Source Coverage Candidates (Compliance-First Path)

Tier 4 sessions (13-14) touch Apify Actor inputs, spend, or collection paths and must clear the compliance-first gate (`docs/sources/apify-source-onboarding.md` plus the matching `source-compliance-<source>.md`) before any network change. If the SQLite observation store lands first, retention (Session 07) and daily-series-adjacent work become SQL policies in that store instead. These dependencies are recorded in each Tier 4 stub, not assumed away.

### Tier Sequencing (From The Mapping)

| Tier                                       | Sessions | Rationale                                                                                                                    |
| ------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| 1 -- scoring integrity, no new surfaces    | 01-03    | Each fixes a correctness/integrity gap in already-collected data; deterministic, no compliance work, no payload risk.        |
| 2 -- derived layers on existing data       | 04-07    | Pure derivations plus one hygiene job; the lifecycle multiplier and named-contribution convention unlock the decision layer. |
| 3 -- decision layer and operator features  | 08-12    | Product-visible features built on Tier 2 outputs; browser-local or view-level work dominates.                                |
| 4 -- collection changes (compliance-gated) | 13-14    | Each touches Actor inputs, spend, or collection paths and needs compliance review or movement-layer coordination first.      |
| Closeout                                   | 15       | Docs, validation, security review, release, and safe deletion of `docs/ongoing-projects/trends-finderz.md`.                  |

Within Tier 1, Session 01 (cross-source fingerprint dedup) is the highest-leverage single item in the mapping: syndicated-story inflation currently distorts the three evidence-driven score factors, and every later layer (aging, saturation, action verdicts) inherits that distortion until dedup lands. Session 03's calibration version stamp is the cheapest -- one constant and three stamps -- and it protects the entire history layer from every other change this phase proposes.

***

## Progress Tracker

| Session | Name                                              | Status   | Est. Tasks | Validated  |
| ------- | ------------------------------------------------- | -------- | ---------- | ---------- |
| 01      | Cross-Source Signal Identity And Dedup            | Complete | 23         | 2026-06-14 |
| 02      | Signal Quality Score And Collection Health        | Complete | 24         | 2026-06-14 |
| 03      | Calibration Version Stamp And Confidence Dampener | Complete | 23         | 2026-06-14 |
| 04      | Topic Noise Gate And Visibility Bands             | Complete | 23         | 2026-06-14 |
| 05      | Signal Aging Half-Lives And Saturation Refinement | Complete | 24         | 2026-06-14 |
| 06      | Lifecycle Multiplier And Named Contributions      | Complete | 23         | 2026-06-14 |
| 07      | Research-Only Calibration And Cache Retention     | Complete | 23         | 2026-06-14 |
| 08      | Per-Topic Action Verdicts And Consistency QA      | Complete | 24         | 2026-06-14 |
| 09      | Action Queue Surface                              | Complete | 18         | 2026-06-14 |
| 10      | Watchlist Pin Baselines, Notes, And Tags          | Complete | 20         | 2026-06-14 |
| 11      | Search Palette And Deterministic Embeddings       | Complete | 25         | 2026-06-14 |
| 12      | Brief QA, Markdown Export, And KPI Strip          | Complete | 25         | 2026-06-14 |
| 13      | Keyword Packs, Rotation, And Coverage QA          | Complete | 25         | 2026-06-14 |
| 14      | Direct First-Party Source Adapters                | Complete | 25         | 2026-06-14 |
| 15      | Documentation Validation And Release              | Complete | 25         | 2026-06-14 |

***

## Completed Sessions

* Session 01: Cross-Source Signal Identity And Dedup - Completed 2026-06-14. Added deterministic URL normalization, content hashes, source-scoped fingerprints, same-source duplicate dropping, cross-source syndication grouping, grouped scoring inputs, browser-safe aggregate counters, sanitized engine trace counters, and focused/full validation coverage.
* Session 02: Signal Quality Score And Collection Health - Completed 2026-06-14. Added bounded cross-source evidence quality scores, quality-first evidence selection and evidence-strength inputs, run-level collection-health duplicate and coverage counters, Sources and Engine Replay rollups, Signal Workbench quality sorting, and focused/full validation coverage.
* Session 03: Calibration Version Stamp And Confidence Dampener - Completed 2026-06-14. Added the shared scoring version constant, snapshot and prediction stamping, cross-version movement and retro provenance flags, bounded sample-confidence dampening, score-breakdown confidence context, Engine Replay scoring-version notices, and focused/full validation coverage.
* Session 04: Topic Noise Gate And Visibility Bands - Completed 2026-06-14. Added deterministic topic-quality scoring, noise risk and visibility bands, bounded reason codes, display-only suppression, early-hidden-gem rescue, Trends and Signal Workbench controls, and focused/full validation coverage.
* Session 05: Signal Aging Half-Lives And Saturation Refinement - Completed 2026-06-14. Added source-role half-life recency, per-topic signal-aging profiles, refined saturation derivation, Trend card and Signal Workbench aging controls, fixtures, documentation, and focused/full validation coverage.
* Session 06: Lifecycle Multiplier And Named Contributions - Completed 2026-06-14. Added bounded lifecycle and aging score movement, ordered named adjustment rows for confidence dampener, lifecycle multiplier, and topic noise downrank, Score Breakdown and Engine Replay rendering, fixtures, documentation, and focused/full validation coverage.
* Session 07: Research-Only Calibration And Cache Retention - Completed 2026-06-14. Added the deterministic `research-only` risk flag from bounded source-role composition, surfaced it through Trend cards and Signal Workbench, added path-safe private snapshot, prediction, and retro archive retention, and validated aggregate-only retention traces and warnings.
* Session 08: Per-Topic Action Verdicts And Consistency QA - Completed 2026-06-14. Added deterministic topic-level action verdicts, hard caps, evidence-to-action QA, blocked verdict demotion, creator-angle caution chips, sanitized trace counts, schema/view-model defaults, fixtures, documentation, and focused/full validation coverage.
* Session 09: Action Queue Surface - Completed 2026-06-14. Added a Brief-first Decisions surface grouped by Act now, Monitor, Review, and Ignore, projected the same bounded model into static Brief exports, added the Signal Workbench decision queue preset, and validated focused/full coverage.
* Session 10: Watchlist Pin Baselines, Notes, And Tags - Completed 2026-06-14. Added versioned browser-local pin baseline snapshots, local notes and normalized tags, deterministic drift projections, separate local Watchlist pinned rows, Trends and Signal Workbench tag filters, and focused storage/view-model/component coverage without mutating generated Watchlist or static Brief output.
* Session 11: Search Palette And Deterministic Embeddings - Completed 2026-06-14. Added an extension-local command palette over loaded Trend Finder payload text, dependency-free feature-hash vectors, hybrid ranking, similarity grouping for deterministic fallbacks, browser-safe payload guards, ADR and manual updates, and focused/full validation coverage.
* Session 12: Brief QA, Markdown Export, And KPI Strip - Completed 2026-06-14. Added static Brief structural and privacy QA before export promotion, bounded manifest QA summaries, browser-safe Markdown and JSON copy flows, a projected Trends run-summary KPI strip, validation-time search empty-state polish, documentation, and focused/full validation coverage.
* Session 13: Keyword Packs, Rotation, And Coverage QA - Completed 2026-06-14. Added reviewed keyword packs, balanced and focused scan modes, deterministic stable-core plus rotating-tail windows, per-source cap compilation for reviewed Apify query fields, sanitized keyword trace evidence, not-scanned movement context, Source Setup coverage QA, docs, and focused/full validation coverage.
* Session 14: Direct First-Party Source Adapters - Completed 2026-06-14. Added compliance-reviewed direct public API adapters for arXiv, GitHub repository search, reviewed RSS feeds, and HN Algolia keyword search, plus frozen readiness, direct-vs-Apify fallback decisions, zero-cost public API spend labels, Source Setup diagnostics, docs, and focused/full validation coverage.
* Session 15: Documentation Validation And Release - Completed 2026-06-14. Updated Trend Finder manuals, Reference mode phrase tests, source-to-doc coverage, security/compliance posture, considerations, Phase 28 PRD records, master PRD status, and changelog notes. Final validation gates pass with the known repo-wide Prettier drift recorded separately from scoped Session 15 formatting proof.

***

## Phase Complete

All Phase 28 implementation sessions are complete and validated. The next workflow step is `audit` to begin phase-transition checks.

***

## Objectives

1. Add cross-source signal identity (URL normalization, content hashes, per-source fingerprints) with within-source dedup and cross-source syndication awareness, so widely syndicated stories stop inflating evidence volume, source diversity, and momentum.
2. Compute one cross-source per-signal quality score and publish per-run duplicate-rate and source-coverage counters in the payload and Sources view.
3. Stamp a scoring calibration version into snapshots and predictions, flag cross-version comparisons, and apply a bounded small-sample confidence dampener with a published confidence value.
4. Add a deterministic topic-quality/noise gate and a derived visibility band with reason codes and a suppressed-noise summary, honoring the existing early-hidden-gem rescue and transparency rules.
5. Add per-role signal-aging half-lives and refine the existing saturation estimate with diffusion and mainstream-term density.
6. Feed lifecycle back into ranking through a bounded multiplier and record every post-factor adjustment as a named contribution in the score breakdown.
7. Add a research-only role-composition risk flag and a retention pruning pass over private snapshot and prediction caches.
8. Add a deterministic per-topic action verdict (act/monitor/review/ignore) with reason codes and an evidence-to-action consistency QA gate, surfaced as Trend card action and caution chips. Action Queue grouping remains Session 09 scope.
9. Extend the browser-local watching pin with a baseline snapshot, drift status, notes, tags, and bounded quality/lifecycle/last-seen metadata where those values already exist in the payload.
10. Add an extension-local search command palette and dependency-free feature-hash embeddings (resolving the Phase 27 embedding ADR) for palette ranking, theme clustering, and fallback clustering.
11. Add static Brief export QA gates with a leak scan, a copy-as-Markdown flow, and a compact KPI run-summary strip.
12. Introduce reviewed keyword packs with scan modes, seeded rotation, and coverage QA, and scope compliance-first direct first-party source adapters.
13. Document, validate, security-review, and release the upgraded surfaces, then delete `docs/ongoing-projects/trends-finderz.md` once coverage is confirmed.

***

## Prerequisites

* Phase 27 completed (Trend Finder Alpha Radar Adoption); its lifecycle, saturation, risk-flag, watching-state, theme-rollup, and embedding-ADR outputs are the baseline this phase reconciles against.
* `EXAMPLES/trends-finderz/` present locally for reference during implementation (read-only source material).
* No open security findings (per `.spec_system/SECURITY-COMPLIANCE.md`).

***

## Technical Considerations

### Architecture

* All collector-side math stays under `scripts/lib/ai-runtime/` and `scripts/extensions/trend-finder/`; browser surfaces consume validated payload fields through `src/extensions/trend-finder/schema.ts` only.
* New schema fields are additive with Zod `.default()` values so legacy payloads, fixtures, and the committed example payload keep parsing.
* Browser-local state (pin baselines, notes, tags) extends the existing Signal Workbench triage / watching storage pattern; the generated Watchlist stays read-only.
* Dedup, quality scoring, and signal-identity helpers are pure string/number math with no new dependencies; embeddings are stdlib SHA-256 feature hashing.
* Persistence-adjacent work (retention, calibration stamps) builds on the private snapshot archives under `.cache/extensions/trend-finder/`; if the SQLite plan lands first, retention becomes a SQL `DELETE` policy and the preserved/deleted split in the trends-finderz README is the policy to copy.
* Tier 4 collection changes (keyword packs, direct adapters) alter Apify Actor inputs and collection paths; they are gated on compliance-doc review and spend-accounting labels, never shipped as silent network changes.

### Technologies

* Zod schema validation (additive defaults).
* Bun scripts for collector/runtime work; Vitest for script and UI tests; Playwright for browser flows (palette keyboard handling, suppressed-noise affordance, Action Queue section).
* Existing AI runtime provider abstraction for any analyst-touching field; all new AI-touching fields need deterministic fallbacks first.
* Stdlib SHA-256 feature-hash embeddings (no model, no vector DB) for search and clustering uses.
* Inline SVG for any new compact visuals (KPI strip, coverage bars).

### Risks

* **Dedup miscalibration**: aggressive cross-source collapsing could erase legitimate role coverage. Mitigation: keep all rows, mark syndicated siblings by content hash, and count a shared story once only for evidence-volume and momentum inputs; test against multi-source fixtures.
* **Payload growth**: new arrays (reason codes, named contributions, action reasons, coverage rows) press the shared 1 MB extension payload limit. Mitigation: bound every new array in the schema and verify payload size in validation.
* **Score-discontinuity from new adjustments**: noise downrank, lifecycle multiplier, and confidence dampener change scores. Mitigation: land the calibration version stamp (Session 03) first so movement and retro layers can flag cross-version comparisons instead of misreading them as movement.
* **Hidden-gem regression**: a noise gate can eat exactly the low-saturation topics Hidden Gems exists to surface. Mitigation: port the early-hidden-gem rescue rule together with the gate, tested against the Phase 27 continuous gem score and `HIDDEN_GEM_CRITERIA`.
* **Compliance drift (Tier 4)**: keyword and direct-adapter changes alter Actor inputs, spend, and collection terms. Mitigation: compliance-doc review and spend-label preservation are explicit in-scope prerequisites for Sessions 13-14; the Apify declarations stay as reviewed fallbacks.
* **Analyst-string overstatement**: an AI angle can overstate thin evidence. Mitigation: the evidence-to-action consistency gate (Session 08) demotes verdicts and labels rather than rewriting AI output.

### Relevant Considerations

* \[P02] **Extension payloads and labels stay bounded**: every new field is bounded and additive; explicit live/fallback/degraded/unavailable states stay intact.
* \[P02] **New source adapters need per-source compliance review**: this gates Sessions 13-14 and keeps the deferred candidates out of earlier sessions.
* \[P05] **Script-only runtime boundary** (lesson): all new math stays under `scripts/lib/` / `scripts/extensions/`; browser code reads validated payload fields only.
* \[P01] **Extract pure functions, then test, then wire** (lesson): dedup, quality score, noise gate, aging, action verdict, and embeddings are each a pure helper with tests before any wiring.
* \[P15] **Aggregate collection must stay budgeted**: any analyst-touching field must respect runtime budgets and degrade to deterministic fallbacks.
* \[P24] **Browser-safe export and triage boundaries**: pin baselines, notes, tags, suppressed-noise summaries, and Markdown export keep local triage and private paths out of exports.
* \[P27] **Trend Finder payload growth needs release checks**: dedup counters, reason codes, action verdicts, coverage rows, and Markdown export require payload, export, privacy, and Reference mode checks together.
* \[P27] **Reference manuals track shipped behavior only**: docs updates in Session 15 must avoid planned-feature language; Engine Replay Reference mode imports committed Markdown.
* \[P27] **Source-to-doc coverage enables safe deletion** (lesson): delete `docs/ongoing-projects/trends-finderz.md` only after source anchors, shipped behavior, deferred candidates, non-goals, and do-not-regress areas are durable in this PRD and the current manuals.
* \[P27] **Deterministic fallback before AI enrichment** (lesson): every trends-finderz feature is deterministic; ship the deterministic version first and treat analyst-touching fields as optional enrichment.
* \[P23] **Backlog migration into phase PRD** (lesson): this phase migrates `docs/ongoing-projects/trends-finderz.md` with source anchors and explicit no-action decisions so the file can be deleted without losing audit history.

***

## Success Criteria

Phase complete when:

* [x] All 15 sessions completed and validated
* [x] Cross-source fingerprint dedup lands; syndicated stories no longer inflate evidence volume, diversity, or momentum, and per-run dedup counters render
* [x] One cross-source per-signal quality score feeds evidence selection, and duplicate-rate plus coverage rollups show in the Sources view
* [x] A scoring calibration version stamps snapshots and predictions, and cross-version comparisons are flagged (not suppressed)
* [x] Topic noise gate, visibility bands, and suppressed-noise summary ship with reason codes and an intact early-hidden-gem rescue
* [x] Per-role aging half-lives and refined saturation render with explicit unavailable states; the six-factor weighted score is not silently changed
* [x] Lifecycle multiplier and confidence dampener surface as named contributions in the score breakdown and Engine Replay
* [x] Research-only risk flag and private archive retention ship with browser-safe aggregate reporting
* [x] Action verdicts, the consistency QA gate, and the Action Queue Brief section ship with reason codes and deterministic fallbacks
* [x] Pin baselines, drift status, notes, tags, and available quality/lifecycle/last-seen metadata work browser-local without mutating the generated watchlist
* [x] The search palette and dependency-free embeddings ship; the Phase 27 embedding ADR decision is resolved
* [x] Static Brief export QA, leak scan, Markdown copy, and KPI strip ship
* [x] Keyword packs/rotation/coverage and direct adapters land only behind compliance-doc review with preserved spend labels (or are explicitly re-deferred with a recorded decision)
* [x] No regression in the "already ahead" areas
* [x] `docs/extensions/trend-finder-*.md` manuals updated; full suite, e2e, and security review pass
* [x] A heading-by-heading coverage check proves every trends-finderz source section and item has a durable destination before source-file deletion
* [x] `docs/ongoing-projects/trends-finderz.md` deleted after coverage check

***

## Dependencies

### Depends On

* Phase 27: Trend Finder Alpha Radar Adoption (lifecycle, saturation, risk flags, watching state, theme rollups, embedding ADR this phase reconciles).
* Phase 24: Trend Finder Outlier Signal Upgrade (source-local signals, Workbench, static Brief export, enrichment cache this phase extends).
* Phase 13: Trend Finder Self-Evaluation Loop (identity, movement, prediction, retro machinery the calibration stamp and action layer build on).

### Enables

* A future source-expansion phase (direct arXiv/GitHub/RSS adapters, keyword packs at full scale) building on the compliance-first scaffolding in Sessions 13-14.
* The SQLite observation store transition (`docs/ongoing-projects/sqlite-observation-store-transition-plan.md`), which can replace Session 07 retention file-pruning with a durable `DELETE` policy and absorb the calibration version stamp into row metadata.


---

# 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/prd_phase_28.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.