> 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/phase28-session04-topic-noise-gate-and-visibility-bands/implementation-notes.md).

# Implementation Notes

**Session ID**: `phase28-session04-topic-noise-gate-and-visibility-bands` **Started**: 2026-06-14 03:10 **Last Updated**: 2026-06-14 04:24

***

## Session Progress

| Metric              | Value     |
| ------------------- | --------- |
| Tasks Completed     | 23 / 23   |
| Estimated Remaining | 3-4 hours |
| Blockers            | 0         |

***

## Task Log

### 2026-06-14 - Session Start

**Environment verified**:

* [x] Prerequisites confirmed with `.spec_system/scripts/analyze-project.sh --json`
* [x] Environment confirmed with `.spec_system/scripts/check-prereqs.sh --json --env`
* [x] Bun 1.3.14 available
* [x] Project-local TypeScript 6.0.3 available at `node_modules/.bin/tsc`
* [x] Project-local Vitest 4.1.6 available at `node_modules/.bin/vitest`
* [x] Directory structure ready

**Scope notes**:

* Current session: `phase28-session04-topic-noise-gate-and-visibility-bands`
* Monorepo: no
* Reference ADR: `docs/adr/0002-trend-finder-embedding-fallback-clustering.md` keeps fallback behavior deterministic and dependency-free.
* Trends-Finderz source files reviewed for topic quality, visibility decisions, and reason labels.

***

### Task T001 - Verify prerequisite sessions, source mapping, and target-file paths before edits

**Started**: 2026-06-14 03:08 **Completed**: 2026-06-14 03:10 **Duration**: 2 minutes

**Notes**:

* Confirmed prerequisite sessions are complete in `.spec_system/state.json` via the analysis script.
* Confirmed Phase 28 Session 04 PRD source mapping references the dependency-free Trends-Finderz topic-quality and visibility-gate helpers.
* Confirmed target files exist except for the planned new helper, summary component, and helper test files.
* Verified no package scope is required because this is not a monorepo session.

**Files Changed**:

* `.spec_system/specs/phase28-session04-topic-noise-gate-and-visibility-bands/implementation-notes.md` - recorded setup verification.

***

### Task T002 - Create implementation-notes shell for scope decisions, validation commands, and deferred items

**Started**: 2026-06-14 03:10 **Completed**: 2026-06-14 03:10 **Duration**: 1 minute

**Notes**:

* Created the session notes shell with progress, environment, scope, and task-log sections.
* Recorded the optional global `tsc` checker mismatch as resolved by project-local tooling through Bun scripts.

**Files Changed**:

* `.spec_system/specs/phase28-session04-topic-noise-gate-and-visibility-bands/implementation-notes.md` - created progress and validation log.

***

### Task T003 - Compare Trends-Finderz topic-quality and visibility constants to current Trend Finder contracts without adding dependencies

**Started**: 2026-06-14 03:10 **Completed**: 2026-06-14 03:12 **Duration**: 2 minutes

**Notes**:

* Reviewed `EXAMPLES/trends-finderz/lib/trends/topic-quality.ts`, `EXAMPLES/trends-finderz/lib/scoring/visibility-gate.ts`, `EXAMPLES/trends-finderz/lib/scoring/suppression-reasons.ts`, and `EXAMPLES/trends-finderz/components/admin/SuppressedNoiseSummary.tsx`.
* Selected the deterministic weak-generic, filler-term, content-pattern, source-confirmation, visibility-status, and reason-code approach.
* Adapted names to Trend Finder browser payload contracts and existing UI/view-model patterns instead of importing reference aliases or UI primitives.
* Preserved the no-new-dependency constraint from the session spec and ADR 0002.

**Files Changed**:

* `.spec_system/specs/phase28-session04-topic-noise-gate-and-visibility-bands/implementation-notes.md` - recorded reference comparison.

***

### Task T004 - Define bounded topic-quality, noise-risk, gate-status, visibility-band, and reason-code schema contracts with additive legacy defaults

**Started**: 2026-06-14 03:12 **Completed**: 2026-06-14 03:15 **Duration**: 3 minutes

**Notes**:

* Added bounded topic-quality, noise-risk, quality-gate, visibility-band, and visibility-reason enums.
* Added neutral `pass` and `watch` defaults so legacy generated payloads parse without migration.
* Added bounded reason-code arrays and inspectable noise-downrank/default rescue fields.
* Added deterministic topic-quality risk flags to the existing risk-flag enum.

**Files Changed**:

* `src/extensions/trend-finder/schema.ts` - added additive topic-quality and visibility contracts.

**BQC Fixes**:

* Contract alignment: kept parser defaults and exported topic type optionality aligned with existing legacy-payload patterns (`src/extensions/trend-finder/schema.ts`).

***

### Task T005 - Create deterministic topic-quality helper with text normalization, generic/filler term penalties, pattern penalties, and source-confirmation scoring with schema-validated input and explicit error mapping

**Started**: 2026-06-14 03:15 **Completed**: 2026-06-14 03:22 **Duration**: 7 minutes

**Notes**:

* Added a pure topic-quality helper with Zod input validation and mapped issue output.
* Implemented deterministic text normalization, generic/filler term penalties, content-pattern penalties, source-confirmation scoring, source-trust scoring, signal-quality scoring, and freshness/actionability metrics.
* Kept helper output bounded to scores, enums, booleans, and reason codes.

**Files Changed**:

* `scripts/lib/ai-runtime/topic-quality.ts` - created deterministic topic-quality helper.

**BQC Fixes**:

* Trust boundary enforcement: validates helper input with Zod and returns explicit issue objects instead of throwing or trusting scoring callers (`scripts/lib/ai-runtime/topic-quality.ts`).
* Error information boundaries: invalid-input issues include validation paths and messages only, not source payload dumps (`scripts/lib/ai-runtime/topic-quality.ts`).

***

### Task T006 - Add visibility-band derivation, machine-readable reason codes, bounded noise downrank, and early-hidden-gem rescue with exhaustive enum handling

**Started**: 2026-06-14 03:22 **Completed**: 2026-06-14 03:24 **Duration**: 2 minutes

**Notes**:

* Added visibility-score, visibility-band, and bounded reason-code derivation.
* Added bounded `topicNoiseDownrank` output for scoring integration.
* Added early-hidden-gem rescue tied to current hidden-gem candidate state, continuous hidden-gem score, low saturation, non-generic topics, and non-cooling movement.
* Added exhaustive switch handling for visibility bands and source-quality tiers.

**Files Changed**:

* `scripts/lib/ai-runtime/topic-quality.ts` - added visibility and rescue derivation.

**BQC Fixes**:

* Contract alignment: returns only enum values defined in the browser schema and filters reason codes through the schema enum order (`scripts/lib/ai-runtime/topic-quality.ts`).

***

### Task T007 - Extend risk-flag derivation for generic-or-vague and high-noise topic flags with schema-validated input and explicit error mapping

**Started**: 2026-06-14 03:24 **Completed**: 2026-06-14 03:26 **Duration**: 2 minutes

**Notes**:

* Added optional topic-quality input to risk-flag derivation.
* Added `generic-or-vague-topic` and `high-noise-topic` flags.
* Kept validation/error mapping in the existing risk-flag result contract.

**Files Changed**:

* `src/extensions/trend-finder/schema.ts` - added risk flag enum members.
* `scripts/lib/ai-runtime/risk-flags.ts` - added topic-quality risk inputs and derivation.

**BQC Fixes**:

* Contract alignment: legacy risk-flag callers continue to parse because topic-quality input is optional (`scripts/lib/ai-runtime/risk-flags.ts`).

***

### Task T008 - Add topic-quality, visibility-band, reason-label, and suppressed-summary view-model projections with bounded result counts and deterministic ordering

**Started**: 2026-06-14 03:26 **Completed**: 2026-06-14 03:31 **Duration**: 5 minutes

**Notes**:

* Added topic-quality and visibility view-model projections with labels, tones, aria labels, and default fallback values.
* Added visibility reason-code labels and deterministic bounded reason ordering.
* Added suppressed-noise summary projection with status counts and top reason counts.
* Updated risk-flag display labels for new topic-quality risk flags.

**Files Changed**:

* `src/extensions/trend-finder/view-model.ts` - added quality, visibility, and suppressed-noise projections.

**BQC Fixes**:

* Error information boundaries: UI view models render bounded labels from enums rather than raw helper strings (`src/extensions/trend-finder/view-model.ts`).
* Accessibility and platform compliance: projected aria labels are provided for quality, visibility, and reason chips (`src/extensions/trend-finder/view-model.ts`).

***

### Task T009 - Wire topic-quality helper into scored topic construction with bounded downrank, fallback-mode behavior, and no raw source leaks

**Started**: 2026-06-14 03:31 **Completed**: 2026-06-14 03:37 **Duration**: 6 minutes

**Notes**:

* Added the topic-quality helper to scored topic construction after base score, sample confidence, saturation, and hidden-gem score are available.
* Added bounded `topicNoiseDownrank` application to the final score.
* Added deterministic fallback-mode caps for high-noise/suppressed and watch-tier fallback topics.
* Published only bounded quality, visibility, reason-code, downrank, and boolean fields to `TrendTopic`.

**Files Changed**:

* `scripts/lib/ai-runtime/scoring.ts` - wired quality helper into scored topic construction.

**BQC Fixes**:

* Contract alignment: scoring writes the same bounded fields defined by the browser schema (`scripts/lib/ai-runtime/scoring.ts`).
* Error information boundaries: scoring passes only bounded evidence metadata and quality scores into the helper, not raw source payloads or private paths (`scripts/lib/ai-runtime/scoring.ts`).

***

### Task T010 - Feed topic-quality outputs into risk-flag construction and preserve hidden-gem status when rescue rules apply

**Started**: 2026-06-14 03:37 **Completed**: 2026-06-14 03:39 **Duration**: 2 minutes

**Notes**:

* Passed topic-quality outputs into risk-flag construction.
* Preserved hidden-gem status when the quality helper reports an early-hidden-gem rescue.
* Calculated hidden-gem candidacy before applying the visibility/downrank adjustment.

**Files Changed**:

* `scripts/lib/ai-runtime/scoring.ts` - added quality-aware risk flags and rescue-aware hidden-gem status.

**BQC Fixes**:

* Contract alignment: risk flags consume the same quality enum values that scoring publishes (`scripts/lib/ai-runtime/scoring.ts`).

***

### Task T011 - Persist parsed topic-quality and visibility fields through payload parsing with bounded reason arrays and legacy-safe defaults

**Started**: 2026-06-14 03:39 **Completed**: 2026-06-14 03:41 **Duration**: 2 minutes

**Notes**:

* Added parser fields for topic quality, noise risk, quality gate, visibility band, visibility score, reason codes, downrank, generic-topic state, and hidden-gem rescue state.
* Added neutral default and catch behavior for new fields so missing or malformed additions do not break older payloads.
* Kept reason-code arrays bounded by `TREND_TOPIC_VISIBILITY_REASON_LIMIT`.

**Files Changed**:

* `src/extensions/trend-finder/schema.ts` - persisted topic-quality and visibility payload fields.

**BQC Fixes**:

* Failure path completeness: malformed new fields fall back to neutral defaults instead of failing the whole Trend Finder payload parse (`src/extensions/trend-finder/schema.ts`).

***

### Task T012 - Render noise-risk, quality-gate, and visibility chips on Trend cards with platform-appropriate accessibility labels and input support

**Started**: 2026-06-14 03:41 **Completed**: 2026-06-14 03:43 **Duration**: 2 minutes

**Notes**:

* Added read-only topic-quality and visibility chips to Trend cards.
* Rendered noise risk, quality gate, visibility band, and hidden-gem rescue state.
* Kept chips bounded with truncation, titles, and explicit aria labels.

**Files Changed**:

* `src/extensions/trend-finder/components/trend-card.tsx` - added topic-quality chip rendering.

**BQC Fixes**:

* Accessibility and platform compliance: chips include aria labels and do not add inaccessible interactive behavior (`src/extensions/trend-finder/components/trend-card.tsx`).

***

### Task T013 - Create suppressed-noise summary component with bounded counts, top reason codes, empty state, and accessible labels

**Started**: 2026-06-14 03:43 **Completed**: 2026-06-14 03:46 **Duration**: 3 minutes

**Notes**:

* Added reusable suppressed-noise summary component.
* Rendered visible/hidden/suppressed/rejected counts, visibility status counts, top reason-code counts, and an empty state.
* Added explicit show/hide toggle semantics for low-signal rows.

**Files Changed**:

* `src/extensions/trend-finder/components/suppressed-noise-summary.tsx` - created summary component.

**BQC Fixes**:

* Accessibility and platform compliance: the show/hide control has pressed state, labels, disabled state, and keyboard-native button behavior (`src/extensions/trend-finder/components/suppressed-noise-summary.tsx`).

***

### Task T014 - Update Trends view to default-hide suppressed rows behind an explicit show/hide affordance with empty, error, offline, and manual-visibility states preserved

**Started**: 2026-06-14 03:46 **Completed**: 2026-06-14 03:49 **Duration**: 3 minutes

**Notes**:

* Added default-hidden filtering for `suppressed` and `rejected` visibility bands.
* Added the suppressed-noise summary and explicit show/hide affordance to the ranked trends panel.
* Preserved existing disabled/error/loading/offline/manual-visibility behavior.
* Reset the derived show-suppressed state when the report re-entry key changes.

**Files Changed**:

* `src/extensions/trend-finder/views/trends-view.tsx` - added default-hidden suppressed topic flow.

**BQC Fixes**:

* State freshness on re-entry: `showSuppressedTopics` resets for each new report key (`src/extensions/trend-finder/views/trends-view.tsx`).
* Accessibility and platform compliance: show/hide is a native button with pressed state from the summary component (`src/extensions/trend-finder/views/trends-view.tsx`).

***

### Task T015 - Add Signal Workbench row fields, facets, filters, and sort keys for visibility band and noise risk with validated filters and deterministic ordering

**Started**: 2026-06-14 03:49 **Completed**: 2026-06-14 03:56 **Duration**: 7 minutes

**Notes**:

* Added topic-quality, noise-risk, visibility-band, visibility-score, reason-label, downrank, suppression, and rescue fields to Workbench rows.
* Added noise-risk and visibility-band filters, facets, and deterministic sort keys.
* Included visibility/noise labels and reason labels in Workbench search text.

**Files Changed**:

* `src/extensions/trend-finder/signal-workbench-model.ts` - added Workbench quality and visibility model support.

**BQC Fixes**:

* Contract alignment: Workbench fields use schema enums and view-model label functions rather than raw enum display (`src/extensions/trend-finder/signal-workbench-model.ts`).

***

### Task T016 - Add Signal Workbench visibility/noise controls with accessible labels, focus management, and keyboard input support

**Started**: 2026-06-14 03:56 **Completed**: 2026-06-14 03:58 **Duration**: 2 minutes

**Notes**:

* Added native select controls for Noise and Visibility filters.
* Reused existing Workbench filter-control styling and update path.

**Files Changed**:

* `src/extensions/trend-finder/components/signal-workbench-controls.tsx` - added visibility/noise filters.

**BQC Fixes**:

* Accessibility and platform compliance: controls use labeled native select elements and existing focus-visible styling (`src/extensions/trend-finder/components/signal-workbench-controls.tsx`).

***

### Task T017 - Update Trend Finder fixtures with representative quality, visibility, reason-code, and rescued-hidden-gem examples while preserving legacy parse coverage

**Started**: 2026-06-14 03:58 **Completed**: 2026-06-14 04:02 **Duration**: 4 minutes

**Notes**:

* Added neutral default quality/visibility values to the fixture topic helper.
* Added a strong visible topic example.
* Added a suppressed ranked topic example with high-noise and quality-gate reason codes.
* Added a rescued hidden-gem topic example.

**Files Changed**:

* `src/extensions/trend-finder/fixtures.ts` - updated fixture topic defaults and representative topic rows.

**BQC Fixes**:

* Contract alignment: fixture examples exercise parser/view-model defaults and explicit new enum values (`src/extensions/trend-finder/fixtures.ts`).

***

### Task T018 - Document shipped topic-quality gate, visibility bands, reason codes, and display-only suppression without planned-feature language

**Started**: 2026-06-14 04:02 **Completed**: 2026-06-14 04:04 **Duration**: 2 minutes

**Notes**:

* Documented shipped topic-quality fields, visibility bands, reason codes, fallback caps, display-only suppression, and early-hidden-gem rescue.
* Updated risk-flag documentation for topic-quality risk flags.

**Files Changed**:

* `docs/extensions/trend-finder-scoring.md` - added topic-quality and visibility behavior.

***

### Task T019 - Write unit tests for topic quality, noise risk, gate status, visibility reasons, and hidden-gem rescue

**Started**: 2026-06-14 04:04 **Completed**: 2026-06-14 04:09 **Duration**: 5 minutes

**Notes**:

* Added pure helper tests for specific pass behavior, generic fallback suppression, visibility reason codes, early-hidden-gem rescue, and invalid-input issue mapping.

**Files Changed**:

* `scripts/lib/ai-runtime/__tests__/topic-quality.test.ts` - added topic-quality unit tests.

***

### Task T020 - Add scoring integration tests for noise downrank, fallback-mode quality bounds, risk flags, and payload retention

**Started**: 2026-06-14 04:09 **Completed**: 2026-06-14 04:13 **Duration**: 4 minutes

**Notes**:

* Added scoring tests for generic-topic downrank, quality-aware risk flags, fallback-mode caps, visibility reason codes, and retained payload rows.

**Files Changed**:

* `scripts/lib/ai-runtime/__tests__/scoring.test.ts` - added quality-gate scoring integration tests.

***

### Task T021 - Add schema and view-model tests for legacy defaults, reason labels, and suppressed summary projection

**Started**: 2026-06-14 04:13 **Completed**: 2026-06-14 04:16 **Duration**: 3 minutes

**Notes**:

* Added legacy parse assertions for missing topic-quality fields.
* Added view-model assertions for quality labels, visibility labels, reason labels, and suppressed summary counts.

**Files Changed**:

* `src/extensions/trend-finder/__tests__/view-model.test.ts` - added topic-quality schema/view-model coverage.

***

### Task T022 - Add Signal Workbench model tests for visibility/noise filters, deterministic ordering, and rescued hidden-gem rows

**Started**: 2026-06-14 04:16 **Completed**: 2026-06-14 04:19 **Duration**: 3 minutes

**Notes**:

* Added Workbench assertions for visibility/noise filtering, search, facets, sort keys, and rescued hidden-gem row projection.

**Files Changed**:

* `src/extensions/trend-finder/__tests__/signal-workbench-model.test.ts` - extended Workbench quality/visibility coverage.

***

### Task T023 - Run focused tests plus ASCII validation and record results with any residual risks

**Started**: 2026-06-14 04:19 **Completed**: 2026-06-14 04:24 **Duration**: 5 minutes

**Notes**:

* Ran focused helper, scoring, view-model, Workbench, and suppressed-noise summary component tests.
* Ran app and script TypeScript checks.
* Ran ASCII scan across touched implementation, test, docs, and session files.
* Residual risk: no browser screenshot/manual visual pass was run in this implement step; validate/manual QA should inspect the Trends ranked list toggle and Workbench filters in the running app.

**Files Changed**:

* `.spec_system/specs/phase28-session04-topic-noise-gate-and-visibility-bands/implementation-notes.md` - recorded validation results.

**Validation Commands**:

* `bunx vitest run scripts/lib/ai-runtime/__tests__/topic-quality.test.ts scripts/lib/ai-runtime/__tests__/scoring.test.ts src/extensions/trend-finder/__tests__/view-model.test.ts src/extensions/trend-finder/__tests__/signal-workbench-model.test.ts src/extensions/trend-finder/components/__tests__/suppressed-noise-summary.test.tsx` - passed, 5 files / 83 tests.
* `bun run typecheck` - passed.
* `bun run typecheck:scripts` - passed.
* `rg --pcre2 -n "[^\\x00-\\x7F]" ...` - passed with no matches.

***

## Session Summary

* Added deterministic topic-quality scoring, noise risk, quality gate, visibility bands, reason codes, bounded downrank, fallback caps, and early-hidden-gem rescue.
* Published additive parser fields with neutral legacy defaults and bounded reason-code arrays.
* Integrated quality outputs into scoring, risk flags, Trend cards, Trends view default suppression, Signal Workbench filters/facets/sorts, fixtures, and docs.
* Added focused tests for helper logic, scoring integration, schema/view-model projection, Workbench filters/sorts, and the suppressed-noise summary control.

***

## Validate Step Notes

**Completed**: 2026-06-14

**Initial validation failures fixed**:

* Full `bun run test` initially failed because the scoring calibration test still expected `trend-finder-scoring-v28.3`, a strong-topic score with no post-confidence downrank, and the Trends hash-target test exposed that suppressed topic deep links fell back to the first visible row.
* Updated `TrendsView` so a valid deep link to a suppressed topic reveals suppressed rows for that report and selects the requested topic.
* Updated scoring calibration coverage for `trend-finder-scoring-v28.4` and bounded topic-noise downrank metadata.
* Removed unused helper imports and tightened optional metadata handling so script typecheck and lint pass.

**Final validation commands**:

* `bun run test` - passed, 288 files / 3516 tests.
* `bun run typecheck` - passed.
* `bun run typecheck:scripts` - passed.
* `bun run lint` - passed.
* `rg --pcre2 -n "[^\\x00-\\x7F]" ...` - passed with no matches.
* `grep -Il $'\\r' ...` - passed with no matches.
* Agent-browser manual pass on local Vite: Trends rendered the suppressed-noise control on current live data; Workbench `NOISE = Low noise` and `VISIBILITY = Watch` filters remained accessible and kept the table populated.


---

# 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/phase28-session04-topic-noise-gate-and-visibility-bands/implementation-notes.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.