> 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-session15-documentation-validation-and-release/spec.md). # Session Specification **Session ID**: `phase28-session15-documentation-validation-and-release` **Phase**: 28 - Trend Finder Trends-Finderz Adoption **Status**: Not Started **Created**: 2026-06-14 *** ## 1. Session Overview This session closes Phase 28 by aligning the committed Trend Finder manuals, Engine Replay Reference mode registry, validation records, and security posture with the behavior shipped across Sessions 01-14. It does not add new Trend Finder features. Its job is to prove that the Trends-Finderz adoption work is documented, validated, release-ready, and safely migrated out of the old planning note. The main product outcome is trust in the upgraded Trend Finder surface. Reference mode imports committed Markdown through `src/extensions/trend-finder/reference-docs.ts`, so the manuals are part of the runtime trust surface. They must describe shipped behavior only: dedup, per-signal quality, calibration, confidence dampening, visibility bands, aging, lifecycle contributions, research-only calibration, action verdicts, Action Queue, watchlist pin baselines, search, Brief QA/export, keyword packs, coverage QA, and direct first-party adapters. The session also completes the safe deletion obligation for `docs/ongoing-projects/trends-finderz.md`. During planning, that file was already absent from the working tree; implementation must not recreate it, and must record a heading-by-heading coverage check before treating the deleted state as complete. *** ## 2. Objectives 1. Update the Trend Finder manuals and Reference mode metadata so they match the shipped Phase 28 behavior and avoid planned-feature language. 2. Preserve deferred source candidates, explicit non-goals, do-not-regress areas, and Trends-Finderz source anchors in durable documentation. 3. Record a heading-by-heading coverage artifact for the retired `docs/ongoing-projects/trends-finderz.md` planning content. 4. Run full validation, payload/privacy checks, Playwright coverage, dependency audit, and security closeout for the completed Phase 28 release. *** ## 3. Prerequisites ### Required Sessions * [x] `phase28-session01-cross-source-signal-identity-and-dedup` - provides dedup behavior and trace counters to document. * [x] `phase28-session02-signal-quality-score-and-collection-health` - provides quality scores and collection-health counters. * [x] `phase28-session03-calibration-version-and-confidence-dampener` - provides scoring version and confidence context. * [x] `phase28-session04-topic-noise-gate-and-visibility-bands` - provides visibility bands and suppressed-noise behavior. * [x] `phase28-session05-signal-aging-half-lives-and-saturation-refinement` - provides aging and refined saturation behavior. * [x] `phase28-session06-lifecycle-multiplier-and-named-contributions` - provides named score contributions. * [x] `phase28-session07-research-only-calibration-and-cache-retention` - provides research-only risk and private retention behavior. * [x] `phase28-session08-action-verdicts-and-consistency-qa` - provides action verdicts and consistency QA. * [x] `phase28-session09-action-queue-surface` - provides Action Queue and Brief projection behavior. * [x] `phase28-session10-watchlist-pin-baselines-notes-tags` - provides browser-local pin baselines, notes, and tags. * [x] `phase28-session11-search-palette-and-deterministic-embeddings` - provides palette search and feature-hash embeddings. * [x] `phase28-session12-brief-qa-markdown-export-and-kpi-strip` - provides Brief QA, Markdown export, and KPI strip behavior. * [x] `phase28-session13-keyword-packs-rotation-and-coverage` - provides keyword packs, scan modes, rotation, and coverage QA. * [x] `phase28-session14-direct-first-party-source-adapters` - provides direct first-party source adapters, readiness, and fallback labels. ### Required Tools/Knowledge * Bun 1.3.14, TypeScript, Vitest, Playwright, Prettier, ESLint, and project scripts from `package.json`. * Current Trend Finder manuals under `docs/extensions/`. * Reference mode registry and tests in `src/extensions/trend-finder/`. * Phase 28 PRD, session stubs, specs, implementation notes, and validation artifacts. * Current security/compliance posture and considerations. ### Environment Requirements * No live AI runtime, Apify, GitHub, RSS, arXiv, HN, or other source credentials are required for this closeout plan. * Generated private artifacts, caches, exported reports, trace files, and `src/data/live-data.json` stay out of git. * Repo-wide formatting drift may be pre-existing; implementation must record whether any format failures are unrelated to the closeout changes. *** ## 4. Scope ### In Scope (MVP) * Trend Finder operators can read current scoring docs - Update scoring guidance for dedup, quality, calibration, confidence dampening, visibility, aging, saturation, lifecycle contributions, research-only risk, action verdicts, and watchlist interpretation. * Trend Finder operators can read current pipeline docs - Update pipeline state and retention guidance for dedup counters, coverage counters, private retention, static Brief QA, payload checks, and source health. * Trend Finder operators can read current UI docs - Update surfaces for visibility bands, suppressed-noise summary, Action Queue, pin baselines, notes, tags, search palette, KPI strip, Markdown export, and Reference mode. * Trend Finder maintainers can audit source behavior - Update source docs for keyword packs, scan modes, rotation, coverage QA, direct adapters, fallback labels, spend labels, and deferred candidates. * Engine Replay can render accurate manuals - Verify or update Reference mode registry metadata, imports, links, and tests. * Reviewers can trace the retired planning source - Record heading-by-heading coverage for source material, method/caveats, items 1.1-10.4, already-ahead areas, non-goals, deferred candidates, and sequencing. * Maintainers can trust release readiness - Run full typecheck, script typecheck, tests, format check, Playwright e2e, static Brief export, payload budget, private-artifact scan, and `bun audit`. * Security posture stays current - Complete a no-new-surface security closeout covering credentials, runtime bridges, admin writes, hosted storage, and transfer paths. * Workflow records are current - Update Phase 28 PRD, master PRD, cumulative security/compliance, and considerations with closeout results. ### Out of Scope (Deferred) * New Trend Finder feature work - *Reason: Sessions 01-14 already shipped the phase behavior; this session is release closeout.* * Re-deriving the Trends-Finderz mapping from scratch - *Reason: the mapping is already folded into the Phase 28 PRD and session stubs.* * New source candidates beyond the reviewed Session 13-14 scope - *Reason: deferred candidates require a future compliance-first phase.* * Recreating `docs/ongoing-projects/trends-finderz.md` - *Reason: the durable destination is the Phase 28 PRD, manuals, and closeout coverage artifact.* * Fixing unrelated repo-wide formatting drift - *Reason: record unrelated drift unless it blocks validation of the session changes.* *** ## 5. Technical Approach ### Architecture Build a source-to-doc coverage artifact before changing or deleting anything. The artifact should map every retired Trends-Finderz planning heading and item to a durable destination: current manuals, Phase 28 PRD sections, session specs, explicit deferrals, or no-action decisions. Update committed Markdown manuals directly. Reference mode should continue to use static imports from `src/extensions/trend-finder/reference-docs.ts`; do not add a dynamic documentation loader or runtime fetch path. If registry labels, descriptions, or tests need changes, keep them additive and stable. Run validation in layers: documentation and Reference mode checks first, focused Trend Finder checks next, then full project quality gates and security checks. Record exact commands, pass/fail outcomes, blockers, and follow-ups in the session implementation notes and validation report. ### Design Patterns * Docs follow implementation: document shipped behavior only. * Committed Markdown as authority: Reference mode imports curated manuals from source files. * Validation before deletion: treat the planning file as deleted only after coverage proves every item has a durable destination. * Project before rendering: static Brief export and Reference mode stay on browser-safe projections and committed docs. * Compliance-first source expansion: deferred source candidates remain documented candidates, not implied approvals. ### Technology Stack * Markdown documentation under `docs/extensions/`. * TypeScript Reference mode registry under `src/extensions/trend-finder/reference-docs.ts`. * Bun scripts, TypeScript, Vitest, Playwright, Prettier, ESLint, and existing shell checks. * Spec-system closeout artifacts under `.spec_system/specs/` and `.spec_system/`. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------- | | `.spec_system/specs/phase28-session15-documentation-validation-and-release/coverage.md` | Heading-by-heading coverage matrix for retired Trends-Finderz planning content, deferred candidates, non-goals, and deletion status. | \~180 | | `.spec_system/specs/phase28-session15-documentation-validation-and-release/implementation-notes.md` | Record docs updates, validation commands, release notes, blockers, and follow-ups during implementation. | \~180 | | `.spec_system/specs/phase28-session15-documentation-validation-and-release/security-compliance.md` | Session security and GDPR closeout for docs, Reference mode, source adapters, export privacy, and no-new-surface review. | \~140 | | `.spec_system/specs/phase28-session15-documentation-validation-and-release/validation.md` | Validate task completion, coverage, commands, privacy checks, and release readiness. | \~180 | ### Files to Modify | File | Changes | Est. Lines | | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `docs/extensions/trend-finder-scoring.md` | Document Phase 28 scoring integrity, dedup, quality, calibration, dampening, aging, saturation, lifecycle contributions, research-only risk, and verdict rules. | \~140 | | `docs/extensions/trend-finder-pipeline.md` | Document collection health, retention pass, payload checks, static Brief QA, export privacy, and source-state transitions. | \~120 | | `docs/extensions/trend-finder-ui-surfaces.md` | Document visibility, suppressed-noise summary, Action Queue, pins, notes, tags, search, KPI strip, Markdown export, and Reference mode. | \~160 | | `docs/extensions/trend-finder-sources.md` | Document keyword packs, scan modes, rotation, coverage QA, direct adapters, fallback behavior, spend labels, and deferred candidates. | \~140 | | `docs/extensions/trend-finder-runtime-and-provenance.md` | Document deterministic fallback, derived provenance, Reference mode boundary, and private-artifact rules after Phase 28. | \~90 | | `docs/extensions/README_docs-extensions.md` | Update current manual list, certification checks, and release guidance for Phase 28 behavior. | \~80 | | `src/extensions/trend-finder/reference-docs.ts` | Verify or update Reference mode labels, descriptions, imports, and source paths for changed manuals. | \~40 | | `src/extensions/trend-finder/__tests__/reference-docs.test.ts` | Cover updated registry metadata, resolvable internal links, required boundary phrases, and no planned-feature drift. | \~80 | | `.spec_system/SECURITY-COMPLIANCE.md` | Add Phase 28 closeout security/GDPR result and latest audit result. | \~90 | | `.spec_system/CONSIDERATIONS.md` | Add Phase 28 lessons, active concerns, deferred candidates, and release follow-ups. | \~90 | | `.spec_system/PRD/phase_28/PRD_phase_28.md` | Mark closeout coverage, validation, security, and deleted-source criteria as satisfied during implementation. | \~80 | | `.spec_system/PRD/PRD.md` | Reflect Phase 28 completion and preserve durable closeout notes in the master PRD. | \~60 | | `docs/CHANGELOG.md` | Add Phase 28 release closeout summary and validation notes. | \~60 | | `docs/ongoing-projects/trends-finderz.md` | Confirm deleted or absent only after coverage artifact proves durable destinations. | deletion | *** ## 7. Success Criteria ### Functional Requirements * [ ] Trend Finder manuals document actual shipped Phase 28 behavior only. * [ ] Engine Replay Reference mode can render the updated manuals through the existing registry. * [ ] Deferred source candidates, explicit non-goals, do-not-regress areas, and Trends-Finderz source anchors survive in durable docs. * [ ] A heading-by-heading coverage artifact maps every retired planning section and item to a durable destination. * [ ] `docs/ongoing-projects/trends-finderz.md` remains deleted or absent only after coverage is verified. * [ ] Security/compliance, considerations, Phase 28 PRD, master PRD, and changelog reflect closeout results. ### Testing Requirements * [ ] `bun run typecheck` passes. * [ ] `bun run typecheck:scripts` passes. * [ ] `bun run test` passes. * [ ] `bun run format:check` passes or unrelated drift is recorded with scoped formatting proof. * [ ] `bun run test:e2e` passes or any environment blocker is recorded with evidence. * [ ] `bun run trend-finder:export-brief` passes. * [ ] `bun run budget:check` passes. * [ ] `bun run runtime:check-private` passes. * [ ] `bun audit` passes. ### Non-Functional Requirements * [ ] Browser-safe payload boundary remains intact. * [ ] Extension payload remains under the shared 1 MB limit. * [ ] No raw prompts, provider responses, credentials, private cache paths, local triage notes, raw source dumps, or raw logs are documented as browser output. * [ ] No new dependency, source adapter, public transfer path, credential flow, admin write, hosted storage, or bridge write surface is introduced. ### Quality Gates * [ ] All files ASCII-encoded * [ ] Unix LF line endings * [ ] Code follows project conventions *** ## 8. Implementation Notes ### Key Considerations * Reference mode renders committed Markdown, so manual updates are user-facing runtime content. * `docs/ongoing-projects/trends-finderz.md` was already absent during planning; implementation should verify coverage and keep it absent rather than recreate it. * The closeout must preserve deferred candidates as compliance-first future work, not approved collection scope. * Validation outputs should separate release blockers from unrelated repository drift. ### Potential Challenges * Existing format drift may cause `bun run format:check` to fail: record the exact unrelated files and run scoped checks for changed files. * Full Playwright e2e may be slow or environment-sensitive: record browser setup blockers with evidence if they occur. * Documentation may accidentally imply planned source expansion is shipped: mitigate with Reference mode phrase tests and explicit deferred-candidate wording. * Payload and privacy checks may generate local artifacts: keep outputs ignored and record only sanitized summaries. ### Relevant Considerations * \[P27] **Reference manuals track shipped behavior only**: Engine Replay Reference mode imports committed Markdown, so docs must avoid planned-feature language. * \[P27] **Source-to-doc coverage enables safe deletion**: delete planning notes only after source anchors, shipped behavior, deferred candidates, non-goals, and do-not-regress areas are durable. * \[P27] **Trend Finder payload growth needs release checks**: payload, export, privacy, and Reference mode checks are one release surface. * \[P27] **Closeout validation should bundle privacy and payload checks**: Reference docs, static Brief export, private-artifact scan, and payload budget should be validated together. * \[P02] **New source adapters need compliance review**: deferred source candidates remain gated and must not be documented as approved adapters. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Reference mode registry drift could break in-app manual rendering. * Manuals could overstate planned or deferred behavior as shipped behavior. * Source-file deletion could lose audit context if coverage is incomplete. * Validation artifacts could expose private paths, cache details, or local generated data. *** ## 9. Testing Strategy ### Unit Tests * Reference docs registry tests for stable metadata, non-empty Markdown, internal Trend Finder link resolution, required boundary phrases, and no planned-feature drift. * Existing Trend Finder unit tests through `bun run test`. ### Integration Tests * TypeScript app and script typechecks. * Static Brief export, payload budget, private-artifact scan, and dependency audit. * Playwright e2e coverage for Trend Finder release surfaces, including Engine Replay Reference mode where available. ### Manual Testing * Open Trend Finder Reference mode and verify updated manuals render with current headings and links. * Spot-check Scoring, Sources, UI Surfaces, and Pipeline manuals against Phase 28 shipped behavior and source deferrals. * Confirm `docs/ongoing-projects/trends-finderz.md` remains absent after the coverage artifact is complete. ### Edge Cases * Missing retired planning file at implementation start. * Markdown links with encoded heading hashes. * Deferred source candidates mentioned without approval or collection claims. * Validation command failures caused by unrelated repository drift. * Generated artifacts containing local private paths or cache references. *** ## 10. Dependencies ### External Libraries * None new. ### Other Sessions * **Depends on**: Phase 28 Sessions 01-14. * **Depended by**: Phase 28 validation/updateprd, phase transition audit, and any future source-expansion phase that uses the durable deferred-candidate record. *** ## 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-session15-documentation-validation-and-release/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.