> 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/phase29-session12-security-lens/spec.md).

# Session Specification

**Session ID**: `phase29-session12-security-lens` **Phase**: 29 - Trend Finder TrendingAI Comparison Adoption **Status**: Not Started **Created**: 2026-06-21

***

## 1. Session Overview

This session adds a bounded security lens to Trend Finder by classifying existing topic evidence for security relevance, severity, and named informational action items. It adopts the useful TrendingAI security-section idea without adding a security feed, raw article inspection, comment-body reads, transcript handling, or any new source/media boundary.

The implementation should reuse the existing reviewed `security` keyword category and only inspect browser-safe normalized evidence fields already present in the generated payload. Non-security fixtures must remain explicitly `unavailable`, and relevant topics should carry compact severity and action labels that explain what an operator should review or monitor without implying automated remediation or execution.

The result should flow through the standard derived-field path: runtime derivation, schema defaulting, required-field closeout registration, live Workbench filtering, static Brief callout, QA/privacy checks, payload-size visibility, and docs. The session is intentionally a lens over current evidence, not a scoring overhaul or source expansion.

***

## 2. Objectives

1. Derive topic-level `securityRelevance` from existing normalized evidence and reviewed security keyword coverage.
2. Publish bounded severity, reason codes, cited evidence IDs, and named informational action items with explicit unavailable states.
3. Add schema defaults, browser-safe validation, required-derived-field closeout registration, and payload-size visibility.
4. Surface the lens as a Signal Workbench filter and compact static Brief callout without changing collection posture.
5. Prove security and non-security fixtures, action-item bounds, privacy cleanliness, payload budget, and legacy defaults with focused tests.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase28-session13-keyword-packs-rotation-and-coverage` - Provides the reviewed keyword taxonomy, including the existing `security` category.
* [x] `phase24-session06-signal-workbench-local-triage` - Provides the Signal Workbench model, filters, controls, and browser-local triage surface.
* [x] `phase29-session08-required-derived-field-closeout-gate` - Provides the closeout gate pattern for required derived fields.
* [x] `phase29-session11-industry-events-rollup` - Confirms the latest report-level derived field, static Brief, QA, and payload-size patterns.

### Required Tools/Knowledge

* Bun 1.3.14 workflow through `bun run test`.
* Existing derived-topic enrichment in `scripts/lib/ai-runtime/source-breakdown.ts`.
* Existing reviewed keyword taxonomy in `scripts/extensions/trend-finder/sources/keyword-packs.ts`.
* Existing Signal Workbench model, controls, table, and view reset behavior.
* Existing static Brief export, renderer, QA, and payload-size scripts.

### Environment Requirements

* Project dependencies installed with Bun.
* No new credential, source, media, database, hosted storage, dependency, or third-party transfer approval is required.

***

## 4. Scope

### In Scope (MVP)

* Trend Finder can classify security relevance over existing topic evidence - Use normalized titles, summaries/snippets, source labels, keyword metadata, and topic names already present in browser-safe payloads.
* Security rows have explicit unavailable behavior - Non-security topics and topics without usable evidence publish `unavailable` rather than guessed severity.
* Severity is bounded and deterministic - Publish only reviewed severity bands such as critical, high, medium, low, or unavailable with reason codes.
* Named action items are informational - Use bounded labels such as review exposure, monitor advisory, validate guardrails, check dependency chain, or track policy change, without instructing automated execution.
* The existing `security` keyword category is reused - Do not add a new source; treat keyword-pack coverage as one signal among the topic's current evidence.
* Browser and static Brief surfaces can show the lens - Add Workbench filter support, compact row chips, static Brief callout, QA checks, and payload-size visibility.
* Release checks prove behavior - Add unit, schema, view-model, Workbench, static Brief, privacy, payload, and ASCII validation coverage.

### Out of Scope (Deferred)

* New security feeds, collectors, or source declarations - Reason: this session reuses existing evidence only.
* Reading raw article bodies, comment bodies, transcripts, provider responses, private diagnostics, or source dumps - Reason: the browser-safe boundary must hold.
* Mutating topic scores, action verdicts, canonical seeds, source packs, or scheduler behavior - Reason: this is a visibility lens, not a ranking or collection session.
* Automated remediation, shell execution, dependency scanning, vulnerability verification, or policy enforcement - Reason: action items stay informational.
* Static Brief archival, One-to-Watch, pre-run estimates, or podcast work - Reason: later Phase 29 sessions own those areas.

***

## 5. Technical Approach

### Architecture

Create a focused `security-lens` helper under `scripts/lib/ai-runtime/`. The helper should own security keyword matching, evidence text normalization, severity selection, reason-code assignment, action-item selection, cited evidence bounds, deterministic ordering, and safe unavailable output. It should consume topics, normalized evidence, sources, and the existing reviewed security keyword pack without fetching or reading any new source material.

Wire the helper from `source-breakdown.ts` while the topic/evidence/source maps are already available. Add a topic-level `securityRelevance` branch in `src/extensions/trend-finder/schema.ts` with `.default()` and `.catch()` fallbacks, max lengths, max action-item counts, cited-evidence validation, and registration in `TREND_REQUIRED_DERIVED_TOPIC_FIELDS`. Keep derivation failures as warnings or unavailable rows rather than blocking unrelated topic output.

Surface the field through `view-model.ts`, `signal-workbench-model.ts`, the Workbench controls/table, Brief export projection, static Brief renderer, static Brief QA, and payload-size reporting. The user-visible copy should be compact, actionable, and explicitly informational; no row should imply execution, automated mitigation, or verified exploitability beyond the existing evidence.

### Design Patterns

* Derived-field shape: derive, validate/default, sanitize, surface, prove, and document.
* Existing source boundary: inspect current normalized evidence only.
* Deterministic fallback: classify from reviewed terms and bounded heuristics without AI runtime dependency.
* Additive schema defaults: older generated payloads parse with unavailable security relevance.
* Safe failure mode: missing evidence, ambiguous matches, and derivation errors produce unavailable output.
* Workbench re-entry reset: filter state revalidates when a new run payload is loaded.

### Technology Stack

* TypeScript for runtime derivation, schema, projections, and React surfaces.
* Zod schemas with `.default()` and `.catch()` for backwards-compatible parsing.
* Bun and Vitest for helper, schema, view-model, static Brief, and Workbench tests.
* Existing Playwright/static Brief checks for browser-visible export behavior.

***

## 6. Deliverables

### Files to Create

| File                                                     | Purpose                                                           | Est. Lines |
| -------------------------------------------------------- | ----------------------------------------------------------------- | ---------- |
| `scripts/lib/ai-runtime/security-lens.ts`                | Security relevance derivation, severity/action taxonomy, bounds.  | \~300      |
| `scripts/lib/ai-runtime/__tests__/security-lens.test.ts` | Unit tests for matching, severity, action items, bounds, privacy. | \~320      |

### Files to Modify

| File                                                                      | Changes                                                                                  | Est. Lines |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------- |
| `scripts/extensions/trend-finder/sources/keyword-packs.ts`                | Expose or reuse the reviewed security keyword category without changing source posture.  | \~30       |
| `scripts/lib/ai-runtime/source-breakdown.ts`                              | Attach `securityRelevance` during topic derived-signal enrichment.                       | \~60       |
| `src/extensions/trend-finder/schema.ts`                                   | Add constants, schema, defaults, topic field, cited-evidence validation, required field. | \~170      |
| `src/extensions/trend-finder/view-model.ts`                               | Add labels, tones, chips, summaries, and export-safe projection helpers.                 | \~140      |
| `src/extensions/trend-finder/signal-workbench-model.ts`                   | Add security filter state, facets, summaries, row fields, and revalidation.              | \~140      |
| `src/extensions/trend-finder/components/signal-workbench-controls.tsx`    | Add accessible security-lens filter control and reset behavior.                          | \~90       |
| `src/extensions/trend-finder/components/signal-workbench-table.tsx`       | Render bounded security severity/action chips in topic rows.                             | \~80       |
| `src/extensions/trend-finder/brief-export-model.ts`                       | Project security lens data into Brief-safe report sections.                              | \~70       |
| `scripts/extensions/trend-finder/static-brief-export.ts`                  | Include security callout data in the static Brief report contract.                       | \~60       |
| `scripts/extensions/trend-finder/static-brief-renderer.ts`                | Render compact security lens callout with cited evidence and empty state.                | \~100      |
| `scripts/extensions/trend-finder/static-brief-qa.ts`                      | Add structure, bounds, and private-string checks for security lens rows.                 | \~70       |
| `scripts/extensions/trend-finder/measure-payload-size.ts`                 | Track `data.topics[].securityRelevance` as a high-pressure branch.                       | \~20       |
| `scripts/lib/ai-runtime/__tests__/source-breakdown.test.ts`               | Cover integration with topic enrichment and unavailable fallback.                        | \~90       |
| `src/extensions/trend-finder/__tests__/view-model.test.ts`                | Cover labels, legacy defaults, Workbench projections, and empty states.                  | \~100      |
| `src/extensions/trend-finder/__tests__/signal-workbench-model.test.ts`    | Cover filters, facets, revalidation, sorting, and non-security rows.                     | \~100      |
| `scripts/extensions/trend-finder/__tests__/static-brief-renderer.test.ts` | Cover security callout rendering and no private strings.                                 | \~80       |
| `scripts/extensions/trend-finder/__tests__/static-brief-qa.test.ts`       | Cover QA bounds, missing cited evidence, and privacy failure mapping.                    | \~70       |
| `scripts/extensions/trend-finder/__tests__/measure-payload-size.test.ts`  | Cover branch visibility for topic security relevance.                                    | \~40       |
| `docs/extensions/trend-finder-pipeline.md`                                | Document derivation, source boundary, unavailable states, and privacy behavior.          | \~40       |
| `docs/extensions/trend-finder-ui-surfaces.md`                             | Document Workbench filter and static Brief security callout behavior.                    | \~30       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Security-relevant fixtures classify with severity, reason codes, cited evidence IDs, and named informational action items.
* [ ] Non-security fixtures remain `unavailable` and do not publish misleading severity.
* [ ] The existing reviewed `security` keyword category is reused without adding or enabling a new source.
* [ ] Signal Workbench exposes a security-lens filter and row chips with platform-appropriate accessibility labels, focus management, and input support.
* [ ] Static Brief renders a compact security callout and a clear empty state.
* [ ] Browser payloads and static Brief output expose no raw article bodies, comment bodies, transcripts, prompts, provider responses, private paths, tokens, credential-shaped strings, or raw source payloads.

### Testing Requirements

* [ ] Unit tests written and passing for matching, severity selection, action-item bounds, cited-evidence bounds, deterministic ordering, and unavailable fallback.
* [ ] Schema and source-breakdown tests prove legacy defaults, cited-evidence validation, required-field closeout, and safe integration.
* [ ] Workbench model/control/table tests prove filtering, row chips, reset on new run payload, and non-security behavior.
* [ ] Static Brief export, renderer, QA, and payload-size tests prove rendering, branch tracking, privacy cleanliness, and failure mapping.
* [ ] Payload-size and static Brief privacy scans remain green.

### Non-Functional Requirements

* [ ] Browser payload stays under the 1 MB extension budget.
* [ ] Derivation is deterministic, bounded, and free of new network calls.
* [ ] Derivation errors degrade to unavailable output without blocking unrelated Trend Finder output.
* [ ] No new source, media, credential flow, database, hosted storage, dependency, shell execution, or third-party transfer is introduced.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] New schema branches use explicit fallback/default behavior.

***

## 8. Implementation Notes

### Key Considerations

* Use only normalized evidence fields already present in the Trend Finder payload.
* Treat the reviewed `security` keyword category as a signal, not as source approval for new collection.
* Prefer conservative unavailable output when evidence is ambiguous or sparse.
* Keep action-item copy informational and bounded; do not tell the operator to execute commands or mutate systems.
* Cite evidence IDs so the lens remains traceable without publishing raw source payloads.
* Register the field with required-derived closeout after the schema default exists so legacy payloads stay parseable.
* Payload-size reporting should make the new topic branch visible because many Phase 29 fields are accumulating on every topic.

### Potential Challenges

* Generic security language may appear in unrelated governance topics: Mitigation is severity thresholds, reviewed keyword matching, and conservative unavailable fallback.
* Action items may read like remediation instructions: Mitigation is a bounded informational taxonomy and copy tests.
* Payload pressure from per-topic action items: Mitigation is max row, action, reason, and citation limits.
* Workbench filter drift after payload reload: Mitigation is existing revalidation and re-entry reset behavior.

### Relevant Considerations

* \[P02] **Extension payloads and labels stay bounded**: The new branch must stay compact and explicitly labeled as available or unavailable.
* \[P24] **Browser-safe export and triage boundaries**: Static Brief and Signal Workbench must not expose local triage notes, raw evidence, private paths, transcripts, prompts, or provider responses.
* \[P27] **Deterministic fallback before AI enrichment**: This session ships a deterministic lens with no AI dependency.
* \[P28] **Direct public source scope is narrow**: Do not imply a new security source approval or source expansion.
* \[P28] **Trend Finder release validation is bundled**: Keep payload-size, static Brief privacy, and documentation validation together.
* \[P00] **Do not document planned features as implemented**: Docs touched during implementation must describe only shipped behavior.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Non-security or ambiguous evidence being presented as a security issue.
* Informational action items implying executable remediation or verified exploitability that the evidence does not prove.
* Raw article bodies, comments, transcripts, provider responses, private paths, or credential-shaped strings leaking into browser payloads or static Brief output.

***

## 9. Testing Strategy

### Unit Tests

* Test non-security evidence produces `unavailable`.
* Test prompt-injection, supply-chain, credential-leak, model-risk, governance, privacy, and red-team fixtures map to bounded severity and reason codes.
* Test action-item selection, max action count, max cited evidence count, deterministic ordering, and text length bounds.
* Test that private-looking paths, raw body fields, credential-shaped strings, and unknown evidence IDs are rejected or omitted.

### Integration Tests

* Test source-breakdown integration attaches `securityRelevance` while preserving source breakdowns, attention pattern, reception, and corroboration.
* Test schema parsing for legacy payloads without `securityRelevance`.
* Test required-derived-field checks include the new field without breaking legacy parse/default behavior.
* Test Workbench filters, facets, table chips, filter reset, and empty states.
* Test static Brief export, renderer, QA, and payload-size branch tracking.

### Manual Testing

* Run focused Vitest suites for security lens, source breakdown, schema, Workbench model, view model, static Brief export/render/QA, and payload size.
* Run payload-size reporting and static Brief privacy checks against a generated or fixture payload.
* Inspect the rendered Workbench and static Brief security callout to confirm copy is compact, traceable, and informational.

### Edge Cases

* No topic evidence or missing evidence IDs.
* Evidence mentions "security" in a company/product name without a concrete security issue.
* Multiple severity terms appear in one topic.
* Security keyword coverage exists but cited evidence is weak or unavailable.
* Browser payload lacks the field because it was generated before this session.

***

## 10. Dependencies

### External Libraries

* No new external libraries.

### Other Sessions

* **Depends on**: `phase28-session13-keyword-packs-rotation-and-coverage`, `phase24-session06-signal-workbench-local-triage`, `phase29-session08-required-derived-field-closeout-gate`
* **Depended by**: `phase29-session18-documentation-validation-and-release`

***

## 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/phase29-session12-security-lens/spec.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.