> 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/spec.md). # Session Specification **Session ID**: `phase28-session04-topic-noise-gate-and-visibility-bands` **Phase**: 28 - Trend Finder Trends-Finderz Adoption **Status**: Not Started **Created**: 2026-06-14 *** ## 1. Session Overview This session adds a deterministic topic-quality gate to Trend Finder so broad, generic, listicle-shaped, or weakly confirmed topic clusters no longer sit next to specific, evidence-backed opportunities as if they were equivalent. The gate is adapted from the Trends-Finderz reference project, but it must follow AI OS rules: no new dependencies, bounded browser payload fields, deterministic fallback behavior, and no raw-source or private-path leakage. The session also adds a derived visibility band with machine-readable reason codes. Topics are never deleted from the payload; instead, low-signal topics are marked as `suppressed` or `rejected`, default-hidden in the Trends view behind an explicit show control, and summarized so the operator can see what was demoted and why. This is the first Tier 2 derived-quality layer in Phase 28. It depends on the completed per-signal quality and scoring-calibration sessions, and it must leave aging refinement, lifecycle multipliers, research-only flags, and action verdicts to later sessions. *** ## 2. Objectives 1. Add a pure deterministic topic-quality helper that derives topic score, clarity, noise risk, and quality-gate status from existing topic, evidence, and scoring inputs. 2. Publish bounded topic-quality, visibility-band, and reason-code fields in the Trend Finder payload with additive defaults for legacy data. 3. Apply a bounded noise downrank and risk-flag integration without silently deleting topics or exposing raw source/private data. 4. Update the Trends and Signal Workbench surfaces so suppressed topics are default-hidden behind an explicit affordance and filterable by reasoned visibility state. *** ## 3. Prerequisites ### Required Sessions * [x] `phase27-session02-deterministic-derived-signals-and-risk-flags` - provides risk flags, saturation, hidden-gem score, and deterministic derived-signal patterns. * [x] `phase27-session06-lifecycle-stage-taxonomy` - provides the current lifecycle vocabulary that this session must not replace. * [x] `phase28-session02-signal-quality-score-and-collection-health` - provides per-signal quality inputs and collection-health context. * [x] `phase28-session03-calibration-version-and-confidence-dampener` - provides scoring-version protection before this session changes ranking. ### Required Tools/Knowledge * Bun 1.3.14 package/runtime commands. * TypeScript, Zod, Vitest, React 19, Tailwind CSS 4, and existing AI OS path aliases. * Trends-Finderz reference files: `EXAMPLES/trends-finderz/lib/trends/topic-quality.ts`, `EXAMPLES/trends-finderz/lib/scoring/visibility-gate.ts`, and `EXAMPLES/trends-finderz/lib/scoring/suppression-reasons.ts`. ### Environment Requirements * Run commands from the repository root. * Keep generated private runtime data, cache files, screenshots, and source dumps out of commits. * Do not add new source adapters, network calls, storage paths, or third-party dependencies. *** ## 4. Scope ### In Scope (MVP) * Trend Finder can compute a deterministic topic-quality score, clarity band, noise risk, and quality-gate status from existing topic/evidence data - implemented as a pure helper with focused tests. * Trend Finder can derive a visibility band and machine-readable reason codes per topic - implemented with bounded enums, bounded reason arrays, and legacy-safe defaults. * Trend Finder can preserve early hidden gems - the visibility gate includes a rescue rule tied to `HIDDEN_GEM_CRITERIA`, hidden-gem score, saturation, and non-stale evidence. * Trend Finder can downrank noisy topics in the default ranked view - bounded penalty fields make the adjustment inspectable now and ready for Session 06 named contributions later. * Operators can inspect suppressed noise - the Trends view default-hides `suppressed` rows behind an explicit "show" affordance and renders a bounded suppressed-noise summary with reason counts. * Operators can triage by visibility state - the Signal Workbench model and controls expose deterministic quality/visibility filters. * Existing legacy payloads parse successfully - missing new fields default to neutral pass/watch behavior rather than crashing. ### Out of Scope (Deferred) * Per-role aging half-lives and saturation refinement - *Reason: Session 05 owns aging and saturation refinement.* * Lifecycle multiplier and named score contributions - *Reason: Session 06 owns the shared adjustment-row convention; this session only records bounded noise downrank data for later migration.* * Research-only risk flag and cache retention pruning - *Reason: Session 07 owns role-composition risk and private-cache retention.* * Per-topic action verdicts and evidence-to-action QA - *Reason: Session 08 consumes visibility and later Tier 2 gates.* * Silently deleting topics from payloads - *Reason: transparency requires display-only suppression with reason codes.* * Replacing manual per-view visibility controls - *Reason: existing operator visibility settings remain the manual override layer.* *** ## 5. Technical Approach ### Architecture Add `scripts/lib/ai-runtime/topic-quality.ts` as the deterministic boundary for topic-quality and visibility decisions. The helper should accept already available scoring/evidence inputs, normalize topic text, apply tuned generic and filler term lists, detect tutorial/listicle patterns, combine source confirmation and signal quality, and return bounded quality and visibility objects with reason codes. Wire the helper from `scripts/lib/ai-runtime/scoring.ts`, after raw score, sample confidence, saturation, hidden-gem score, and lifecycle inputs are available. The scoring layer should write new payload fields, apply a bounded noise downrank to final ranking output, and pass quality data into the existing risk-flag derivation. Browser parsing stays in `src/extensions/trend-finder/schema.ts` with additive defaults. Project the new fields through `src/extensions/trend-finder/view-model.ts` and the existing dense Trend Finder UI patterns. `trends-view.tsx` should split ranked topics into visible and suppressed sets, render a suppressed-noise summary, and provide an explicit accessible control for showing hidden low-signal rows. Signal Workbench should add deterministic filters, not local storage mutation or new persistence. ### Design Patterns * Pure function, then tests, then wire: keeps deterministic scoring changes reviewable and matches prior script-helper sessions. * Zod additive defaults: new fields must parse old generated payloads and fixtures without migration. * Browser-safe projection: publish enums, counts, bounded labels, and reason codes only; do not publish raw prompts, source dumps, private paths, or unbounded strings. * Display-only suppression: low-signal topics remain in payloads and can be inspected by the operator. ### Technology Stack * Bun 1.3.14 for scripts and test execution. * TypeScript for application and script code. * Zod for payload parsing and defaulting. * React 19 and Tailwind CSS 4 for UI changes. * Vitest for script, schema, view-model, and component coverage. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------- | | `scripts/lib/ai-runtime/topic-quality.ts` | Pure topic-quality, noise-risk, visibility-band, reason-code, and hidden-gem rescue helper | \~280 | | `scripts/lib/ai-runtime/__tests__/topic-quality.test.ts` | Unit tests for quality scoring, noise risk, gate status, visibility reasons, and rescue behavior | \~240 | | `src/extensions/trend-finder/components/suppressed-noise-summary.tsx` | Trends view summary for suppressed/rejected topic counts and top reason codes | \~160 | ### Files to Modify | File | Changes | Est. Lines | | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------- | | `scripts/lib/ai-runtime/scoring.ts` | Call topic-quality helper, apply bounded noise downrank, publish fields, feed risk flags | \~100 | | `scripts/lib/ai-runtime/risk-flags.ts` | Add quality/noise-aware risk flag inputs and flags | \~60 | | `src/extensions/trend-finder/schema.ts` | Add enums, defaults, bounded reason arrays, and parsed topic fields | \~140 | | `src/extensions/trend-finder/view-model.ts` | Add topic-quality, visibility, and suppressed-summary view models | \~130 | | `src/extensions/trend-finder/components/trend-card.tsx` | Render noise/gate/visibility chips with accessible labels | \~70 | | `src/extensions/trend-finder/views/trends-view.tsx` | Default-hide suppressed rows and add explicit show/hide affordance | \~100 | | `src/extensions/trend-finder/signal-workbench-model.ts` | Add quality/visibility fields, facets, filters, and deterministic sorting | \~100 | | `src/extensions/trend-finder/components/signal-workbench-controls.tsx` | Add visibility/noise filter controls | \~50 | | `src/extensions/trend-finder/fixtures.ts` | Add representative fixture values where needed for UI coverage | \~40 | | `docs/extensions/trend-finder-scoring.md` | Document shipped topic-quality and visibility behavior only | \~40 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Generic or listicle-shaped topics get deterministic medium/high noise risk and are downranked without being removed from the payload. * [ ] Visibility bands carry machine-readable reason codes and bounded display labels. * [ ] Early hidden gems stay visible when they meet the rescue rule and are not high-noise, stale, or unsupported. * [ ] The Trends view default-hides `suppressed` topics behind an explicit control that lists how many low-signal topics were hidden and why. * [ ] Manual per-view visibility controls continue to work as the operator override layer. * [ ] Signal Workbench can filter by visibility band or noise risk. * [ ] Legacy payloads parse with neutral defaults and existing fixtures remain usable. ### Testing Requirements * [ ] Unit tests written and passing for topic-quality scoring, gate status, reason codes, and hidden-gem rescue. * [ ] Scoring integration tests cover downrank behavior, fallback-mode quality bounds, and risk-flag integration. * [ ] Schema/view-model tests cover legacy parsing and suppressed summary projection. * [ ] Component or route tests cover default-hidden suppressed rows and the show affordance. * [ ] Manual testing completed for Trends and Signal Workbench surfaces. ### Non-Functional Requirements * [ ] No new dependencies, source adapters, storage paths, external calls, or credential flows are introduced. * [ ] Browser payload additions remain bounded and keep the shared payload-size discipline. * [ ] Reason strings and labels are bounded, deterministic, and ASCII-safe. * [ ] No raw source dumps, private paths, prompt text, or token-shaped strings are exposed in UI summaries or generated data. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Focused tests pass. * [ ] Type checking remains clean for changed files. *** ## 8. Implementation Notes ### Key Considerations * The helper should reuse existing scoring inputs instead of re-fetching or re-analyzing evidence. * Numeric thresholds from Trends-Finderz are starting points; tune conservatively for Trend Finder's source roles and current scoring ranges. * The `suppressed` band is a display decision, not a deletion decision. * The early-hidden-gem rescue must be implemented with the current `HIDDEN_GEM_CRITERIA` and hidden-gem score so the gate does not erase the low-saturation topics Hidden Gems is meant to surface. * Session 06 will introduce named contribution rows. This session should record a bounded noise downrank field so that later migration is straightforward. ### Potential Challenges * Threshold overreach: mitigate with tests that compare specific generic, weakly confirmed, and legitimate early-gem examples. * UI confusion between derived suppression and manual visibility settings: mitigate with copy and state that clearly separates "low-signal topics hidden" from operator-hidden rows. * Payload growth: mitigate with enums, small reason arrays, max string lengths, and fixture/legacy parsing tests. * Future-session overlap: do not add aging status, lifecycle multipliers, research-only flags, or action verdicts in this session. ### Relevant Considerations * \[P01] **Old `claude-os-*` naming**: Do not add new `findtrend`, `claude-os`, or host-identity names for Trend Finder fields. * \[P02] **Extension payloads and labels stay bounded**: New fields must be bounded enums, counts, and short labels to preserve the payload boundary. * \[P24] **Browser-safe export and triage boundaries**: Suppressed summaries and Workbench filters must not expose private paths, raw evidence dumps, or local triage notes. * \[P27] **Trend Finder payload growth needs release checks**: Include legacy parse, payload-boundary, and static summary checks as part of validation. * \[P27] **Reference manuals track shipped behavior only**: Any doc update must describe implemented topic-quality behavior, not later action verdict plans. * \[P00] **Stack conventions**: Keep Bun, TypeScript, Zod, React, Tailwind, and Cloudflare Worker compatibility assumptions intact. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Derived suppression could hide valuable early signals unless the hidden-gem rescue is explicit and tested. * Legacy generated data could crash new UI unless schema defaults are additive and view models tolerate missing fields. * A topic list with suppressed rows could change unexpectedly unless sorting, filtering, and show/hide controls are deterministic and accessible. *** ## 9. Testing Strategy ### Unit Tests * Test topic text normalization, generic/filler term penalties, listicle pattern penalties, source confirmation effects, noise risk, gate status, and visibility reason-code output. * Test hidden-gem rescue against current `HIDDEN_GEM_CRITERIA`, hidden-gem score, saturation, evidence count, and high-noise exclusions. ### Integration Tests * Test `scoreTrendTopics` publishes topic-quality fields, applies bounded downrank, and keeps topics in the payload. * Test risk flags include quality/noise-derived flags only when helper outputs justify them. * Test schema and view-model behavior for legacy payloads with no new fields. ### Manual Testing * Open Trends with a fixture containing suppressed and visible topics; confirm suppressed rows are hidden by default, the summary count is visible, and the show control reveals reason-coded rows. * Open Signal Workbench and confirm visibility/noise filters update rows deterministically without layout overlap. ### Edge Cases * Empty topic labels, one-word generic labels, all-filler labels, and labels containing technical named entities. * Single-source high-quality topics versus multi-source generic topics. * Hidden gems with low saturation and thin evidence. * Legacy payloads missing every new field. * Offline or fallback-mode generated reports. *** ## 10. Dependencies ### External Libraries * None. Use existing TypeScript, Zod, React, Tailwind, and Vitest tooling. ### Other Sessions * **Depends on**: `phase27-session02-deterministic-derived-signals-and-risk-flags`, `phase27-session06-lifecycle-stage-taxonomy`, `phase28-session02-signal-quality-score-and-collection-health`, and `phase28-session03-calibration-version-and-confidence-dampener`. * **Depended by**: `phase28-session06-lifecycle-multiplier-and-named-contributions` and `phase28-session08-action-verdicts-and-consistency-qa`. *** ## 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/phase28-session04-topic-noise-gate-and-visibility-bands/spec.md?ask=&goal= ``` `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.