> 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-session07-research-only-calibration-and-cache-retention/implementation-notes.md). # Implementation Notes **Session ID**: `phase28-session07-research-only-calibration-and-cache-retention` **Started**: 2026-06-14 06:03 **Last Updated**: 2026-06-14 07:38 *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 23 / 23 | | Estimated Remaining | 0 hours | | Blockers | 0 | *** ## Task Log ### 2026-06-14 - Session Start **Environment verified**: * [x] Prerequisites confirmed * [x] Tools available * [x] Directory structure ready ### Task T001 - Verify prerequisite sessions and target paths **Started**: 2026-06-14 06:00 **Completed**: 2026-06-14 06:03 **Duration**: 3 minutes **Notes**: * Confirmed `phase28-session07-research-only-calibration-and-cache-retention` is the active session from `.spec_system/scripts/analyze-project.sh --json`. * Confirmed prerequisite sessions are marked complete in state output and the session PRD names the current extension points. * Verified this is not a monorepo session and target files are repo-root paths under `scripts/`, `src/extensions/trend-finder/`, and `docs/extensions/`. **Files Changed**: * `.spec_system/specs/phase28-session07-research-only-calibration-and-cache-retention/implementation-notes.md` - Created implementation progress log. **BQC Fixes**: * N/A - setup verification only. ### Task T002 - Create implementation-notes shell **Started**: 2026-06-14 06:03 **Completed**: 2026-06-14 06:04 **Duration**: 1 minute **Notes**: * Created the session implementation notes with environment verification, task log, design decision, validation, and residual-risk sections. * Seeded the notes with the research-only calibration boundary decision so later docs and tests stay aligned with the existing risk flag framework. **Files Changed**: * `.spec_system/specs/phase28-session07-research-only-calibration-and-cache-retention/implementation-notes.md` - Added the session log shell and initial setup entries. **BQC Fixes**: * N/A - spec artifact only. ### Task T003 - Compare Trends-Finderz calibration and retention policy **Started**: 2026-06-14 06:04 **Completed**: 2026-06-14 06:05 **Duration**: 1 minute **Notes**: * Reviewed the Trends-Finderz research calibration helper. It models `research_only` as a caution state when research signals exist without non-research confirmation. * Reviewed the Trends-Finderz retention cleanup helper and README policy. AI OS should copy the preserve/delete policy shape, not the 30-day database threshold. * Calibrated this session to AI OS source roles: `research-only` requires research evidence and absence of developer, discussion, and launch roles. * Retention constants stay file-cache specific: default 180 days, lower clamp above the 84-day historical window, and aggregate-only reporting. **Files Changed**: * `.spec_system/specs/phase28-session07-research-only-calibration-and-cache-retention/implementation-notes.md` - Recorded comparison and threshold decisions. **BQC Fixes**: * N/A - reference analysis only. ### Task T004 - Add research-only schema enum and legacy parsing **Started**: 2026-06-14 06:06 **Completed**: 2026-06-14 06:07 **Duration**: 1 minute **Notes**: * Added `research-only` to `TREND_TOPIC_RISK_FLAGS` so it remains ordered by the existing risk flag contract. * Added a Zod catch fallback on topic `riskFlags` so malformed generated arrays fall back to the bounded default instead of breaking legacy payload parsing. **Files Changed**: * `src/extensions/trend-finder/schema.ts` - Added the enum value and safe fallback. **BQC Fixes**: * Contract alignment: kept a single public `riskFlags` array and reused the existing enum ordering. * Failure path completeness: malformed flag arrays now parse to default bounded state. ### Task T005 - Extend risk flag derivation with role composition **Started**: 2026-06-14 06:07 **Completed**: 2026-06-14 06:10 **Duration**: 3 minutes **Notes**: * Added bounded role-composition input to `deriveTopicRiskFlags`. * Unknown or malformed roles normalize to `unknown`; invalid role-composition arrays fall back to empty. * `research-only` is appended only when research evidence exists, developer/discussion/launch roles are absent, and research share meets the local 0.75 threshold. * Final output remains ordered by `TREND_TOPIC_RISK_FLAGS`. **Files Changed**: * `scripts/lib/ai-runtime/risk-flags.ts` - Added role schema, threshold constant, adoption-role exclusions, and derivation logic. **BQC Fixes**: * Trust boundary enforcement: role-composition input is schema-validated and malformed values are bounded. * Contract alignment: output shape stays `RiskFlagDerivationResult` with no new public flag framework. ### Task T006 - Wire scoring risk derivation to source roles **Started**: 2026-06-14 06:11 **Completed**: 2026-06-14 06:14 **Duration**: 3 minutes **Notes**: * Reused the scoring-time evidence context to derive aggregate role shares before source breakdowns are attached. * Added a shared role-share helper for lifecycle and risk flag inputs to keep duplicate evidence handling consistent. * Passed aggregate role composition into `deriveTopicRiskFlags`; no raw source rows or private source details are exposed. **Files Changed**: * `scripts/lib/ai-runtime/scoring.ts` - Added role-composition wiring for risk derivation. **BQC Fixes**: * Duplicate action prevention: role counts dedupe evidence IDs before computing shares. * Contract alignment: scoring still emits a single bounded `riskFlags` array. ### Task T007 - Add research-only risk flag view-model copy **Started**: 2026-06-14 06:14 **Completed**: 2026-06-14 06:15 **Duration**: 1 minute **Notes**: * Added bounded label, description, and warning tone for `research-only`. * Existing `getTopicRiskFlagViewModels` composes aria labels from the shared label/description, so Trend card chips and Workbench labels share the same copy. **Files Changed**: * `src/extensions/trend-finder/view-model.ts` - Added risk flag label, description, and tone. **BQC Fixes**: * Accessibility and platform compliance: aria text is generated from the new bounded label and description through the existing chip view-model path. ### Task T008 - Add snapshot archive retention helper **Started**: 2026-06-14 06:15 **Completed**: 2026-06-14 06:21 **Duration**: 6 minutes **Notes**: * Added snapshot retention constants: default 180 days, minimum 90 days, maximum 730 days. * The helper prunes only dated JSON files inside the resolved snapshot directory and preserves `latest.json`, subdirectories, non-JSON entries, and unclassified JSON names. * Warnings are sanitized code/count summaries without private paths or filenames. **Files Changed**: * `scripts/lib/ai-runtime/snapshots.ts` - Added retention clamp, path-safe prune helper, date classification, and sanitized warning summary. **BQC Fixes**: * Resource cleanup: delete operations are bounded to files inside the resolved archive directory. * Trust boundary enforcement: retention days are clamped and deletion targets pass path containment. * Failure path completeness: missing directories, read failures, unclassified entries, and delete failures return warning codes and counts. ### Task T009 - Add research-only fixture data **Started**: 2026-06-14 06:22 **Completed**: 2026-06-14 06:27 **Duration**: 5 minutes **Notes**: * Added `topic-006` as a representative research-only topic with two research sources, role share 1.0, and the `research-only` risk flag. * Added two fixture evidence rows and a Hugging Face Papers research source so UI and parser tests can cover a multi-source research-only topic. * Existing `topic-004` remains a mixed research/developer counterexample for non-trigger behavior. **Files Changed**: * `src/extensions/trend-finder/fixtures.ts` - Added research-only topic, evidence, and source fixture rows. **BQC Fixes**: * Contract alignment: fixture roles, source breakdowns, evidence IDs, and risk flags use existing schema fields. ### Task T010 - Add prediction archive retention helper **Started**: 2026-06-14 06:28 **Completed**: 2026-06-14 06:33 **Duration**: 5 minutes **Notes**: * Added prediction archive retention constants matching snapshot policy. * The helper lists only the prediction archive directory, preserves `latest.json`, preserves the nested `retros` directory, and prunes only expired dated JSON files. * Returned warnings contain sanitized code/count summaries only. **Files Changed**: * `scripts/lib/ai-runtime/predictions.ts` - Added prediction retention clamp, prune helper, and summary utilities. **BQC Fixes**: * Resource cleanup: deletion is limited to dated prediction archive files under the resolved archive directory. * Trust boundary enforcement: retention days are clamped and deletion targets use path containment. * Failure path completeness: missing/read/delete/unclassified paths return bounded warning summaries. ### Task T011 - Add retro archive retention helper **Started**: 2026-06-14 06:34 **Completed**: 2026-06-14 06:39 **Duration**: 5 minutes **Notes**: * Added retro archive retention under `predictions/retros` with the same 180/90/730-day clamp. * The helper preserves `latest.json`, subdirectories, non-JSON entries, and unclassified JSON files. * Retro counts and warning codes are returned independently from prediction archive counts. **Files Changed**: * `scripts/lib/ai-runtime/retros.ts` - Added retro retention clamp, prune helper, and summary utilities. **BQC Fixes**: * Resource cleanup: deletion is limited to dated retro archive files under the resolved retro directory. * Trust boundary enforcement: deletion targets use the existing retro path containment guard. * Failure path completeness: missing/read/delete/unclassified cases are reported through bounded warning summaries. ### Task T012 - Invoke retention after archive writes **Started**: 2026-06-14 06:40 **Completed**: 2026-06-14 06:47 **Duration**: 7 minutes **Notes**: * Added collector dependency hooks for snapshot, prediction, and retro retention helpers. * Retention runs after prediction/retro archives and the snapshot archive have been written. * Added a per-collect-run guard so retention is only triggered once in the collector flow. **Files Changed**: * `scripts/extensions/trend-finder/collector.ts` - Added retention dependencies, runner invocation, and one-run guard. **BQC Fixes**: * Duplicate action prevention: retention invocation is guarded by `archiveRetentionStarted` for the active collect run. * Failure path completeness: store failures produce bounded collector warnings and do not prevent other stores from pruning. ### Task T013 - Emit sanitized retention trace events and warnings **Started**: 2026-06-14 06:47 **Completed**: 2026-06-14 06:48 **Duration**: 1 minute **Notes**: * Retention trace event `trend-cache.retention.completed` includes store names, retention days, cutoff, counts, and warning codes only. * Store-level failures emit `trend-cache.retention.failed` with a bounded code. * Collector warnings use `trend-cache-retention-degraded` and include only store/count/code summaries. * The returned Engine Replay trace is rebuilt after retention so the browser payload receives sanitized retention counts, not file paths. **Files Changed**: * `scripts/extensions/trend-finder/collector.ts` - Added sanitized retention trace and warning projection. **BQC Fixes**: * Error information boundaries: warnings and trace summaries exclude deleted filenames, absolute paths, and raw error text. * Contract alignment: browser-visible trace receives bounded store/count/code fields only. ### Task T014 - Ensure Trend card risk chips render research-only **Started**: 2026-06-14 06:49 **Completed**: 2026-06-14 06:50 **Duration**: 1 minute **Notes**: * Confirmed Trend cards render risk chips from `RiskFlagChipViewModel`, so `research-only` flows through the existing view-model path. * Added explicit max-width and wrapping-safe classes to risk chips for compact labels. **Files Changed**: * `src/extensions/trend-finder/components/trend-card.tsx` - Tightened chip wrapping behavior while preserving aria/title attributes. **BQC Fixes**: * Accessibility and platform compliance: `aria-label` and `title` remain bound to the view-model description. * Contract alignment: no separate `research-only` component path was introduced. ### Task T015 - Ensure Signal Workbench risk facets include research-only **Started**: 2026-06-14 06:51 **Completed**: 2026-06-14 06:53 **Duration**: 2 minutes **Notes**: * Confirmed Workbench rows and facets derive risk flags from `TREND_TOPIC_RISK_FLAGS`, so `research-only` inherits deterministic ordering. * Added an exported empty-risk summary constant to make no-risk row behavior explicit and testable. **Files Changed**: * `src/extensions/trend-finder/signal-workbench-model.ts` - Added explicit empty risk summary constant and reused it in row projection. **BQC Fixes**: * Contract alignment: Workbench filtering remains tied to the shared enum instead of a duplicate list. ### Task T016 - Update scoring documentation **Started**: 2026-06-14 06:54 **Completed**: 2026-06-14 06:57 **Duration**: 3 minutes **Notes**: * Added a shipped risk flag section to the scoring guide. * Documented `research-only` as a deterministic caution chip derived from aggregate role composition. * Clarified that the flag is an input for later review and action consistency checks, not an action verdict by itself. **Files Changed**: * `docs/extensions/trend-finder-scoring.md` - Added the current risk flag table and research-only semantics. **BQC Fixes**: * Contract alignment: documentation matches the single public `riskFlags` array and existing score-factor boundaries. ### Task T017 - Update pipeline documentation **Started**: 2026-06-14 06:57 **Completed**: 2026-06-14 07:00 **Duration**: 3 minutes **Notes**: * Updated the aggregate run sequence to include post-write private archive retention and sanitized trace rebuild. * Documented retention stores, default/clamped window, env override, preserve list, path containment, and browser-safe count reporting. **Files Changed**: * `docs/extensions/trend-finder-pipeline.md` - Added archive retention policy and reporting details. **BQC Fixes**: * Error information boundaries: documentation explicitly forbids deleted filenames, absolute paths, and raw filesystem errors in browser payloads. ### Task T018 - Record implementation decisions and residual risks **Started**: 2026-06-14 06:03 **Completed**: 2026-06-14 07:01 **Duration**: 58 minutes **Notes**: * Recorded setup findings, role threshold rationale, retention constants, preserve-list policy, BQC checks, and changed files as implementation progressed. * Validation commands remain pending until focused tests and ASCII checks run. * Residual risks remain pending until test results are known. **Files Changed**: * `.spec_system/specs/phase28-session07-research-only-calibration-and-cache-retention/implementation-notes.md` - Maintained task log, design decisions, validation placeholders, and risk placeholders. **BQC Fixes**: * N/A - spec artifact only. ### Task T019 - Add risk flag and scoring tests **Started**: 2026-06-14 07:02 **Completed**: 2026-06-14 07:08 **Duration**: 6 minutes **Notes**: * Added direct `deriveTopicRiskFlags` coverage for research-only detection, adoption-role exclusions, malformed role normalization, and deterministic ordering. * Added scoring integration tests for pure research-role topics and mixed developer/research counterexamples. **Files Changed**: * `scripts/lib/ai-runtime/__tests__/risk-flags.test.ts` - Added research-only derivation tests. * `scripts/lib/ai-runtime/__tests__/scoring.test.ts` - Added scoring integration tests. **BQC Fixes**: * Contract alignment: tests assert `research-only` stays in the existing ordered flag array. ### Task T020 - Add schema, view-model, and Workbench tests **Started**: 2026-06-14 07:09 **Completed**: 2026-06-14 07:14 **Duration**: 5 minutes **Notes**: * Updated schema tests for additive `research-only` parsing and fallback behavior for unknown risk flags. * Added view-model checks for research-only label, warning tone, description, and aria text. * Added Workbench filter/facet coverage for `research-only` using the new fixture topic, plus explicit no-risk summary coverage. **Files Changed**: * `src/lib/__tests__/trend-finder-schema.test.ts` - Updated risk flag parsing expectations. * `src/extensions/trend-finder/__tests__/view-model.test.ts` - Added chip copy assertions. * `src/extensions/trend-finder/__tests__/signal-workbench-model.test.ts` - Added facet/filter/empty summary assertions. **BQC Fixes**: * Accessibility and platform compliance: tests assert aria text includes the bounded risk chip label. * Contract alignment: Workbench tests use the shared enum-derived facet path. ### Task T021 - Add archive retention tests **Started**: 2026-06-14 07:15 **Completed**: 2026-06-14 07:24 **Duration**: 9 minutes **Notes**: * Added snapshot, prediction, and retro retention tests for clamp behavior, `latest.json` preservation, subdirectory preservation, malformed/unclassified file preservation, deletion counts, and sanitized summaries. **Files Changed**: * `scripts/lib/ai-runtime/__tests__/snapshots.test.ts` - Added snapshot retention test. * `scripts/lib/ai-runtime/__tests__/predictions.test.ts` - Added prediction retention test. * `scripts/lib/ai-runtime/__tests__/retros.test.ts` - Added retro retention test. **BQC Fixes**: * Resource cleanup: tests verify only expired dated JSON files are removed. * Error information boundaries: tests verify retention summaries do not include temp cache paths. ### Task T022 - Add collector retention tests **Started**: 2026-06-14 07:25 **Completed**: 2026-06-14 07:29 **Duration**: 4 minutes **Notes**: * Added collector coverage for one end-of-collect retention invocation across snapshots, predictions, and retros. * Asserted aggregate per-store prune counts, warning propagation, sanitized Engine Replay warnings, and no private cache-path leakage in browser-visible payloads. * Allowed retention warnings to stay code/count based so preserved entries such as `latest.json`, subdirectories, and unclassified files remain observable without filenames or paths. **Files Changed**: * `scripts/extensions/trend-finder/__tests__/collector.test.ts` - Added retention invocation, warning, trace, and path-leak assertions. **BQC Fixes**: * Resource cleanup: collector tests verify all three archive stores are pruned once after writes. * Error information boundaries: tests verify retention trace and warning summaries exclude private cache paths. ### Task T023 - Run validation and dry-run checks **Started**: 2026-06-14 07:30 **Completed**: 2026-06-14 07:38 **Duration**: 8 minutes **Notes**: * Ran focused Trend Finder tests across risk derivation, scoring, schema parsing, view-model projection, Signal Workbench filtering, archive retention helpers, and collector integration. * Ran app and scripts typechecks. * Ran Prettier over touched files and verified the formatted result. * Ran ASCII validation over changed and untracked session files. * Ran a manual smoke script over the fixture data for the `research-only` chip, Signal Workbench risk filter/facet, and temp archive retention pruning. **Files Changed**: * `.spec_system/specs/phase28-session07-research-only-calibration-and-cache-retention/implementation-notes.md` - Recorded final validation results and residual risks. * `.spec_system/specs/phase28-session07-research-only-calibration-and-cache-retention/tasks.md` - Marked final tasks and completion checklist. **BQC Fixes**: * Accessibility and platform compliance: manual smoke verified the `research-only` chip label and warning tone. * Resource cleanup: manual smoke verified one expired writer-style archive file is pruned per store. * Error information boundaries: manual smoke verified retention summaries did not include the temp cache path. *** ## Design Decisions ### Decision 1: Research-only calibration boundary **Context**: Trends-Finderz has a richer evidence-level system with confidence impacts, but AI OS already has a bounded risk flag framework. **Options Considered**: 1. Add a new evidence-level contract - broader than session scope and duplicates the existing flag system. 2. Extend the existing risk flag array - additive, schema-safe, and automatically surfaces in existing chip and Workbench ordering paths. **Chosen**: Extend the existing risk flag array. **Rationale**: The session explicitly requires compatibility by extension and Session 08 can consume `research-only` as one more caution input. ### Decision 2: Retention window and preserve policy **Context**: Trend Finder reads 84 days of historical context and long-lived installs write private snapshot, prediction, and retro archives indefinitely. **Options Considered**: 1. Copy Trends-Finderz 30-day database cleanup - too short for AI OS historical context and retro review. 2. Use a 180-day file-cache default with a lower clamp above the 84-day history window - preserves context while bounding local growth. **Chosen**: Use a 180-day default, 90-day minimum, and 730-day maximum for private archive retention. **Rationale**: The lower clamp stays above the 84-day read window, and the maximum prevents accidental unbounded retention. *** ## Validation Commands * `bun test ./scripts/lib/ai-runtime/__tests__/risk-flags.test.ts ./scripts/lib/ai-runtime/__tests__/scoring.test.ts ./scripts/lib/ai-runtime/__tests__/snapshots.test.ts ./scripts/lib/ai-runtime/__tests__/predictions.test.ts ./scripts/lib/ai-runtime/__tests__/retros.test.ts ./src/lib/__tests__/trend-finder-schema.test.ts ./src/extensions/trend-finder/__tests__/view-model.test.ts ./src/extensions/trend-finder/__tests__/signal-workbench-model.test.ts ./scripts/extensions/trend-finder/__tests__/collector.test.ts` - Passed, 302 tests. * `bun run typecheck` - Passed. * `bun run typecheck:scripts` - Passed. * `bunx prettier --check` over changed and untracked implementation files - Passed. * ASCII scan over changed and untracked files with `rg -nP '[^\x00-\x7F]'` - Passed, no matches. * Manual `bun --eval` smoke for Trend card risk chip projection, Signal Workbench `research-only` filter/facet, and temp archive retention pruning - Passed. ## Residual Risks * `research-only` is intentionally a caution input only. Session 08 still owns action consistency and action-verdict behavior. * Retention intentionally preserves unclassified JSON filenames and reports sanitized skip counts instead of risking deletion of reviewed or malformed artifacts. --- # 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-session07-research-only-calibration-and-cache-retention/implementation-notes.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.