> 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-session14-direct-first-party-source-adapters/tasks.md).

# Task Checklist

**Session ID**: `phase28-session14-direct-first-party-source-adapters` **Total Tasks**: 25 **Estimated Duration**: 3-4 hours **Created**: 2026-06-14

***

## Legend

* `[x]` = Completed
* `[ ]` = Pending
* `[P]` = Parallelizable (can run with other \[P] tasks)
* `[SNNMM]` = Session reference (NN=phase number, MM=session number)
* `TNNN` = Task ID

***

## Progress Summary

| Category       | Total  | Done   | Remaining |
| -------------- | ------ | ------ | --------- |
| Setup          | 4      | 4      | 0         |
| Foundation     | 7      | 7      | 0         |
| Implementation | 10     | 10     | 0         |
| Testing        | 4      | 4      | 0         |
| **Total**      | **25** | **25** | **0**     |

***

## Setup (4 tasks)

Initial configuration and environment preparation.

* [x] T001 \[S2814] Verify Session 14 prerequisites, completed dependency sessions, and direct-source compliance gate requirements before source network work (`.spec_system/PRD/phase_28/session_14_direct_first_party_source_adapters.md`)
* [x] T002 \[S2814] Re-review and update direct arXiv and GitHub API compliance docs with rate limits, approved fields, retention, attribution, and blocked/deferred decisions (`docs/sources/source-compliance-arxiv.md`)
* [x] T003 \[S2814] Re-review and update direct RSS/feed and HN Algolia compliance docs with per-feed approval, current-only scope, field exclusions, and fallback stance (`docs/sources/source-compliance-rss-news.md`)
* [x] T004 \[S2814] Update Apify source onboarding with direct first-party gating, fallback-to-Apify behavior, no-duplicate collection, and zero-cost spend label requirements (`docs/sources/apify-source-onboarding.md`)

***

## Foundation (7 tasks)

Core structures and base implementations.

* [x] T005 \[S2814] Extend source adapter contracts with direct readiness, fallback policy, direct source declarations, and diagnostics with schema-validated input and explicit error mapping (`scripts/extensions/trend-finder/sources/types.ts`)
* [x] T006 \[S2814] \[P] Create shared direct-source fetch, timeout, retry/backoff, abort cleanup, safe URL, XML/JSON parsing, and warning redaction helpers with cleanup on scope exit for all acquired resources (`scripts/extensions/trend-finder/sources/direct-source-utils.ts`)
* [x] T007 \[S2814] \[P] Create direct connector readiness helper with disabled/degraded/ready labels, compliance blocked states, fallback decisions, and no activation after collection starts (`scripts/extensions/trend-finder/sources/direct-source-readiness.ts`)
* [x] T008 \[S2814] \[P] Create direct arXiv adapter foundation with reviewed query construction, 3-second pacing, metadata-only parsing, no PDF/contact fields, and timeout/retry failure handling (`scripts/extensions/trend-finder/sources/arxiv-adapter.ts`)
* [x] T009 \[S2814] \[P] Create direct GitHub adapter foundation with bounded search queries, optional script-only token support, rate-limit header handling, public metadata normalization, and PII exclusions (`scripts/extensions/trend-finder/sources/github-adapter.ts`)
* [x] T010 \[S2814] \[P] Create direct RSS adapter foundation with reviewed feed allowlist, RSS/Atom parsing, private/local URL rejection, item caps, and malformed-feed degraded states (`scripts/extensions/trend-finder/sources/rss-adapter.ts`)
* [x] T011 \[S2814] Extend HN type constants for Algolia keyword search responses, current-only support, and bounded request defaults (`scripts/extensions/trend-finder/sources/hn-types.ts`)

***

## Implementation (10 tasks)

Main feature implementation.

* [x] T012 \[S2814] Add HN Algolia keyword collection path with explicit loading, empty, error, rate-limited, and offline states while preserving safe top-stories fallback behavior (`scripts/extensions/trend-finder/sources/hn-adapter.ts`)
* [x] T013 \[S2814] Add direct arXiv, GitHub, RSS, and HN Algolia normalization helpers with types matching declared contracts, exhaustive enum handling, and browser-safe field projection (`scripts/extensions/trend-finder/normalize.ts`)
* [x] T014 \[S2814] Link direct adapters to existing Apify source declarations and fallback metadata without removing reviewed Apify declarations (`scripts/extensions/trend-finder/sources/apify-source-config.ts`)
* [x] T015 \[S2814] Add Apify skip handling for direct-active source IDs with duplicate-trigger prevention while in-flight and explicit fallback summaries when direct paths fail (`scripts/extensions/trend-finder/sources/apify-adapter.ts`)
* [x] T016 \[S2814] Register direct adapters in collector, resolve readiness before collection, freeze readiness for the run, and trace direct/fallback decisions with sanitized diagnostics (`scripts/extensions/trend-finder/collector.ts`)
* [x] T017 \[S2814] Attach zero-cost public API spend summaries to direct source rows while preserving mixed direct-plus-Apify aggregation and deterministic source ordering (`scripts/extensions/trend-finder/spend-accounting.ts`)
* [x] T018 \[S2814] Include direct readiness diagnostics and direct-vs-Apify status in source setup summaries with bounded pagination, validated filters, and deterministic ordering (`scripts/extensions/trend-finder/sources/source-setup.ts`)
* [x] T019 \[S2814] Add browser schema defaults and view-model labels for direct readiness, disabled states, fallback labels, and long diagnostic text bounds (`src/extensions/trend-finder/schema.ts`)
* [x] T020 \[S2814] Render direct readiness and fallback labels in Source Setup with state reset or revalidation on re-entry and platform-appropriate accessibility labels (`src/extensions/trend-finder/components/source-setup-panel.tsx`)
* [x] T021 \[S2814] Update Trend Finder source docs for shipped direct adapters, readiness states, zero-cost labels, Apify fallbacks, and explicitly deferred source candidates (`docs/extensions/trend-finder-sources.md`)

***

## Testing (4 tasks)

Verification and quality assurance.

* [x] T022 \[S2814] \[P] Add direct utility and readiness tests for timeout, retry, abort cleanup, safe URLs, redaction, disabled/degraded/ready states, fallback selection, and no activation after collection starts (`scripts/extensions/trend-finder/sources/__tests__/direct-source-utils.test.ts`)
* [x] T023 \[S2814] \[P] Add direct arXiv, GitHub, RSS, and HN adapter tests for normalization, rate limits, retries, timeouts, empty/error/offline states, PII exclusions, and zero-cost spend labels (`scripts/extensions/trend-finder/sources/__tests__/arxiv-adapter.test.ts`)
* [x] T024 \[S2814] \[P] Add collector, Apify fallback, source setup, view-model, Source Setup component, and spend tests for direct-first ordering, duplicate suppression, fallback behavior, re-entry rendering, and mixed spend aggregation (`scripts/extensions/trend-finder/__tests__/collector.test.ts`)
* [x] T025 \[S2814] Run focused tests, script/app type checks, aggregate smoke without Apify credentials, payload/private-artifact checks, and ASCII validation for all session files (`package.json`)

***

## Completion Checklist

Before marking session complete:

* [x] All tasks marked `[x]`
* [x] All tests passing
* [x] All files ASCII-encoded
* [x] implementation-notes.md updated
* [x] Ready for the validate workflow step

***

## Next Steps

Run the validate workflow step for independent verification.


---

# 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-session14-direct-first-party-source-adapters/tasks.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.