feat: SourceAdapter pattern + SourceRegistry (#1)

.squad/agents/bunk/history.md

@@ -11,3 +11,22 @@
 ## Learnings
 
 - First session: team initialized 2026-03-05
+- **Reddit JSON API:** Requires User-Agent header, respects X-RateLimit headers, returns 1 request per 2 seconds (~30 requests/min)
+- **Stack Overflow API:** 300 req/day free (10k with key); `/search/advanced.json` is the query endpoint; timestamps are Unix epoch
+- **Bluesky atproto:** Fully open, no auth required, generous rate limits, standard REST API at https://public.api.bsky.app/xrpc
+- **Mastodon:** Instance-specific APIs, typically `/api/v1/timelines/tag/{hashtag}`, HTML-escaped content requires unescaping
+- **X/Twitter:** API is now paid (formerly free); Elevated tier ~$5k/month; low ROI for Aspire discovery (high noise)
+- **Discord:** Requires bot setup + human server admin approval; historical message API is paginated (100 messages per call)
+- **GitHub Discussions:** Supported by REST API, separate from Issues, not yet queried in community.ts
+- **Canonical IDs:** Team uses sha256(id+url+author+date), hex 16 chars; ensures deterministic dedupe
+- **Community source priority:** Reddit > Stack Overflow > GitHub Discussions (quick wins); defer X/LinkedIn/Discord until budget/access confirmed
+
+#### Cross-Agent Findings (from squad sync 2026-03-12)
+
+**Signal gap analysis (Omar):** Reddit is critical for real-time pain signals and adoption friction detection. Stack Overflow captures eternal pain patterns that inform content strategy. Together, these unlock medium-term editorial intelligence.
+
+**Content discovery (Kima):** RSS feeds are lowest-friction source; blog platforms via API add engagement metrics. Multi-source deduplication is critical. Recommend implementing Dev.to API alongside Reddit and Stack Overflow.
+
+**Architecture recommendation (Freamon):** Design community sources as SourceAdapter modules. Each source (GitHub, Reddit, Stack Overflow, etc.) becomes self-contained with its own rate limiting, error handling, and validation.
+
+**Team consensus:** Phase 1 (Reddit + Stack Overflow + Dev.to) gives Beth 50% signal completeness. Phase 2 (YouTube) adds creator mapping. Phase 3 deferred until early wins stabilized.

.squad/agents/freamon/history.md

@@ -11,3 +11,56 @@
 ## Learnings
 
 - First session: team initialized 2026-03-05
+- **Architecture patterns**:
+   - Current discovery structure (content.ts / community.ts) is monolithic and won't scale beyond 3-4 sources
+   - Recommendation: Adapter pattern with SourceAdapter interface for plug-and-play source extensibility
+   - Registry pattern (SourceRegistry) for auto-discovery, validation, and parallel execution
+   - Each adapter owns: env var requirements, rate limiting, error handling, validation logic
+- **Source prioritization for Beth**:
+   - Phase 1 (quick wins): Reddit JSON API, Dev.to API, Stack Overflow API — no auth, immediate value
+   - Phase 2 (API-key): YouTube Data API, podcast RSS — high value, requires config
+   - Phase 3 (hard): Social media scrapers (X/LinkedIn/Bluesky), conference crawlers — high effort
+- **Key file paths**:
+   - Discovery modules: src/discovery/content.ts, src/discovery/community.ts
+   - Types: src/types.ts (all interfaces: ContentItem, DiscoveryResult, RunState, etc.)
+   - Taxonomy: src/taxonomy.ts (dedupe + classification logic)
+   - Pipeline: src/index.ts (orchestrator: load → discover → dedupe → classify → analyze → output)
+   - Output: src/output.ts (generates all 9 reports)
+   - State: src/state.ts (persists RunState to AspireContentEngine/.state/)
+- **User preferences**:
+   - Brady prioritizes editorial intelligence breadth (cover as many sources as possible)
+   - Beth needs signal quality over volume (actionability: amplify/respond more important than raw counts)
+   - Team prefers TypeScript, lean on Node.js built-ins, avoid heavy dependencies unless necessary
+
+#### Cross-Agent Findings (from squad sync 2026-03-12)
+
+**Signal analysis (Omar):** Architecture refactor will unlock 50% signal completeness (Phase 1), 65% with Phase 2 (YouTube), 82% with all sources. Current bottleneck is monolithic discovery files.
+
+**Community discovery (Bunk):** Prioritizes Reddit > Stack Overflow > GitHub Discussions for immediate Phase 1 value. X/Twitter deferred due to API cost (\/month). LinkedIn deferred in favor of link enrichment.
+
+**Content discovery (Kima):** RSS expansion + YouTube + podcasts gives 85%+ blog coverage. Multi-source deduplication strategy (sha256 canonical IDs) scales to 20+ sources.
+
+**Squad consensus:** Refactor first (2.5 sessions), then Phase 1 (2-3 sessions). This gives Brady technical debt cleanup + Beth immediate editorial ROI. Phase 2 & 3 follow after Phase 1 validation.
+
+#### PRD Authoring Session (2026-03-12)
+
+**Issues filed:** 7 GitHub PRDs on bradygaster/ACCES (issues #1-#7), all labeled `squad`
+- **Issue #1:** Architecture Refactor (McNulty + Stringer, 2.5 sessions) — foundation for all adapters
+- **Issues #2-#5:** Phase 1 adapters (Reddit, Dev.to, Stack Overflow, GitHub Discussions) — 3.5 sessions total
+- **Issues #6-#7:** Phase 2 adapters (YouTube, Podcasts) — 2.5 sessions total
+
+**PRD structure used:**
+- Overview (what + why for Beth)
+- Background (gap analysis context)
+- Requirements (implementation checklist)
+- Squad SDK Integration (adapter patterns)
+- Acceptance Criteria (testable outcomes)
+- Dependencies (issue blocking relationships)
+- Assigned To (squad member ownership)
+- Estimated Effort (session count)
+
+**Dependency chain:** Issue #1 blocks all others. Phase 1 issues (#2-#5) can parallelize after #1. Phase 2 issues (#6-#7) follow Phase 1 validation.
+
+**Key learning:** GitHub CLI required account switch (`gh auth switch --user bradygaster`) when working with personal repos while logged into Enterprise Managed User account. All issues created successfully after switch.
+
+**Deliverable:** Summary written to `.squad/decisions/inbox/freamon-prd-issues.md` for Ralph's triage.

.squad/agents/kima/history.md

@@ -10,4 +10,40 @@
 
 ## Learnings
 
-- First session: team initialized 2026-03-05
+### Session 2026-03-05: Content Source Gap Analysis
+
+#### Discovered Patterns
+- **RSS feeds are the lowest-friction source:** Dev.to, Microsoft blogs all use RSS. This pattern should be expanded to podcasts and any new feeds discovered.
+- **Multi-source deduplication is critical:** Same content (esp. talks) reappear across YouTube, blogs, social media, conferences. Need a robust canonical ID strategy.
+- **API availability varies widely:** Official Microsoft channels have simple URLs; YouTube/Reddit are well-documented; Substack/Medium are either deprecated or behind scraping concerns.
+
+#### Key Implementation Notes
+- All sources feed into `ContentItem` type from `src/types.ts` — no custom models needed
+- `generateCanonicalId()` function (SHA256 of title+url+author+date) is stable and reusable
+- `isAspireRelated()` + `isExcluded()` helpers should remain the core relevance filter
+- Topic extraction via keyword matching works well for broad categories; fine-tuning will happen later
+
+#### Architecture Decisions
+- **Blog discovery strategy:** Start with RSS for low-friction sources (podcasts), then layer Hashnode API (free, clean). Defer Medium scraping until yield metrics justify the effort.
+- **Social media:** X API and Bluesky are viable; LinkedIn is blocked (TOS). Recommend X + Bluesky for Phase 2.
+- **Conferences:** No single API. Must implement per-conference (NDC scraper first, then .NET Conf, Build). Manual watchlist is acceptable until volume justifies automation.
+- **Podcast feeds:** Expand `RSS_FEEDS` constant to include 5–10 known .NET podcasts. Zero API cost, high long-tail value.
+
+#### For Next Scout Sessions
+- YouTube implementation should leverage `@googleapis/youtube` package; start with simple title-based search
+- Reddit can use either RSS (lower friction) or PRAW (higher signal); recommend RSS-first approach for simplicity
+- When implementing blog platforms, coordinate with Bubbles (taxonomy scout) on topic inference; many platforms use custom tag systems
+- All new sources should write raw evidence to `/raw/` folder (JSON snippets of API responses or feed excerpts) for auditability
+
+#### Files Modified / Created
+- `.squad/decisions/inbox/kima-content-source-gaps.md` — Primary deliverable (gap analysis)
+
+#### Cross-Agent Findings (from squad sync 2026-03-12)
+
+**Signal gap analysis (Omar):** Content sources alone capture ~85% of blog content but only 40% of overall tech adoption signals. YouTube, podcast, and conference discovery will significantly improve coverage.
+
+**Community discovery (Bunk):** GitHub is fully implemented for community signals but covers only ~20% of real community conversation. Reddit, Stack Overflow, and GitHub Discussions are critical quick wins.
+
+**Architecture recommendation (Freamon):** Implement SourceAdapter pattern before adding 6+ new sources. Current monolithic structure (content.ts, community.ts) needs refactoring for scale.
+
+**Team consensus:** Prioritize Phase 1 (Reddit, Dev.to, Stack Overflow) for immediate editorial value; Phase 2 (YouTube, podcasts) adds creator/influencer coverage; Phase 3 (social, conferences) is secondary.

.squad/agents/mcnulty/history.md

@@ -21,3 +21,8 @@
 - Pipeline flow: loadState → discoverContent + discoverCommunity → deduplicate → classify → analyze → generateOutput → saveState
 - Canonical ID = sha256(title|url|author|date).slice(0,16)
 - The `Channel` type uses `(string & {})` pattern to allow known unions + arbitrary strings
+- `generateCanonicalId` is duplicated in `content.ts` (line 214) and `taxonomy.ts` (line 88) — must consolidate during SourceAdapter refactor
+- `truncate` helper is duplicated in `content.ts` and `community.ts` — consolidate into shared helpers module
+- Skeleton discovery functions (blog search, YouTube, Reddit, social media) all return `[]` — safe to remove during adapter extraction
+- Enterprise Managed User (EMU) GitHub account can't use GraphQL for issue comments — use `gh issue comment --body-file` with REST API instead
+- Produced implementation plan for Issue #1 (SourceAdapter pattern) — posted to https://github.com/bradygaster/ACCES/issues/1#issuecomment-4045230035 and `.squad/decisions/inbox/mcnulty-issue1-plan.md`

.squad/agents/omar/history.md

@@ -10,4 +10,53 @@
 
 ## Learnings
 
-- First session: team initialized 2026-03-05
+### Architecture & Implementation
+
+- **Two-scout model**: `discoverContent()` (blogs/RSS) and `discoverCommunity()` (GitHub) are separate pipelines, both returning `DiscoveryResult[]` to be merged and deduplicated
+- **GitHub is the only live community source**: Issues, PRs, and repo metadata provide GitHub signal; Reddit/social/YT/podcasts are stubs waiting implementation
+- **Canonical ID strategy**: Content is deduplicated via `generateCanonicalId(title, url, author, date)` — SHA256 hash, deterministic across runs
+- **Signal classification happens late**: `tags.signal` is populated post-discovery (e.g., `inferIssueSignal()` for GitHub issues; RSS items default to `['other']`)
+- **Taxonomy is inclusive**: All channels/types/topics are extensible strings; no hard enums except for the core types (`ContentType`, `Channel`, `Signal`, etc.)
+
+### Signal Gaps (Key Finding)
+
+- **Current completeness**: ~32% (RSS + GitHub only) — Beth sees blogs and repos, misses community friction
+- **Critical blind spots** (in order):
+  1. **Reddit** (real-time pain signals, adoption friction, sentiment) — HIGH priority
+  2. **Stack Overflow** (eternal pain patterns, docs gaps) — MEDIUM-HIGH priority
+  3. **YouTube** (creator ecosystem, tutorial gaps, reach) — HIGH priority
+  4. **Social media X/LinkedIn** (amplification, mood, decision-makers) — MEDIUM-HIGH priority
+  5. **Podcasts** (industry narrative, thought leadership) — MEDIUM priority
+- **Projected completeness with all sources**: 82% — would give Beth ~4/5 of the conversation
+
+### User Needs (Beth's Perspective)
+
+- **Editorial priorities**: Detection of pain points, creator mapping, gap filling, amplification queues
+- **Real-time vs. batch**: Blogs can be daily; GitHub/Reddit/X are real-time; SO/podcasts are evergreen/weekly
+- **Actionability hierarchy**: Amplify > Respond > Follow-up > Investigate > Ignore (tagged on every item)
+- **Sentiment is missing**: No current way to measure community mood; social signals + Reddit would unlock this
+
+### File Paths & Key Code
+
+- **Discovery modules**: `src/discovery/content.ts` (RSS) and `src/discovery/community.ts` (GitHub)
+- **Analysis**: `src/analysis.ts` generates trends, gaps, amplifications from classified items
+- **Taxonomy**: `src/taxonomy.ts` (not viewed yet) handles classification
+- **Run state**: `.state/` directory persists `known_ids` and `known_dupes` for dedup across runs
+- **ACCES spec**: `ACCES.md` is the ground truth for output format and role definitions
+
+### First Session Outputs
+
+- **Signal gaps document**: `.squad/decisions/inbox/omar-signal-gaps.md` — detailed analysis of 5 missing signal types, completeness framework, and implementation priority roadmap
+- **Recommendation**: Start with Reddit + SO (high impact, medium effort); defer podcasts to medium term
+
+- First session: team initialized 2026-03-05; signal gap analysis completed 2026-03-05
+
+#### Cross-Agent Findings (from squad sync 2026-03-12)
+
+**Community discovery (Bunk):** Reddit and Stack Overflow address the largest signal blind spots. Reddit captures real-time pain/confusion (15% → 50% completeness). Stack Overflow captures eternal patterns and docs gaps.
+
+**Content discovery (Kima):** YouTube is the second-highest-priority discovery source for creator ecosystem mapping. Currently 0% coverage; Phase 2 implementation will address creator influence gap.
+
+**Architecture recommendation (Freamon):** Phased rollout requires adapter pattern foundation. Suggests SourceAdapter interface with validation, rate limiting, and graceful error handling built into each source module.
+
+**Team consensus:** Phase 1 → 50% completeness (Reddit, Dev.to, Stack Overflow). Phase 2 → 65% completeness (add YouTube). Phase 3 → 82% completeness (add social, podcasts, conferences). Recommend refactor before Phase 1 implementation.

.squad/agents/scribe/history.md

@@ -1,16 +1,60 @@
-# Project Context
+# Scribe — History
 
-- **Project:** Acces
-- **Created:** 2026-03-05
+## Project Context
 
-## Core Context
+- **Project:** ACCES — Aspire Community Content Engine Squad
+- **Role:** Documentation specialist maintaining history, decisions, and technical records
+- **Owner:** bradygaster (Brady), with Beth Massi as the primary customer/user
+- **Purpose:** Consolidate squad outputs, maintain decision registry, cross-agent knowledge sharing
 
-Agent Scribe initialized and ready for work.
+## Learnings
 
-## Recent Updates
+### Session 2026-03-12: Squad Output Consolidation
 
-📌 Team initialized on 2026-03-05
+#### Responsibilities Completed
+1. ✅ Orchestration logs for 4 agents (Kima, Bunk, Omar, Freamon)
+2. ✅ Session log entry
+3. ✅ Merged decision inbox files into decisions.md (4 major decisions documented)
+4. ✅ Updated all agent history files with cross-agent findings
+5. ✅ Git commit of .squad/ directory
 
-## Learnings
+#### Key Findings from Agent Reports
+
+**Signal Completeness Analysis (Omar):**
+- Current: 32% (RSS + GitHub only)
+- Phase 1: 50% (add Reddit, Dev.to, Stack Overflow)
+- Phase 2: 65% (add YouTube)
+- Phase 3: 82% (add social, podcasts, conferences)
+
+**Community Discovery Gaps (Bunk):**
+- Reddit: High priority, 40-80 posts/week, medium effort
+- Stack Overflow: Medium priority, 20-60 questions/week, low-medium effort
+- X/Twitter: Deferred due to API cost ($5k/month)
+- Discord: Deferred, requires server admin approval
+
+**Content Discovery Gaps (Kima):**
+- RSS expansion: Low effort, immediate value
+- YouTube: High value, requires API key
+- Podcasts: Medium value, no auth required
+- Conferences: Medium-high effort per conference
+
+**Architecture Recommendation (Freamon):**
+- Implement SourceAdapter pattern before adding 6+ new sources
+- Refactor timeline: 2.5 sessions (prevents technical debt)
+- Phase 1: 2-3 sessions (quick wins)
+- Phase 2: 2-3 sessions (YouTube, podcasts)
+- Phase 3: 4-6 sessions (social, conferences, HN)
+
+#### Files Created/Modified
+- `.squad/orchestration-log/2026-03-12T09-15-15Z-*.md` — 4 agent execution logs
+- `.squad/log/2026-03-12T09-15-15Z-scribe.md` — Session log
+- `.squad/decisions.md` — Merged 4 major decisions from inbox
+- `.squad/agents/*/history.md` — Updated all 4 agent files with cross-team findings
+- `.squad/decisions/inbox/` — Deleted after merge (managed by git)
+
+#### Cross-Agent Insights
+- **Consensus:** Refactor → Phase 1 → Phase 2 → Phase 3 sequencing
+- **Priority alignment:** Reddit > Stack Overflow > YouTube > Podcasts
+- **Architecture:** SourceAdapter pattern unblocks scale to 20+ sources
+- **Timeline:** Phase 1 implementation gives 50% signal completeness in 2-3 sessions
 
-Initial setup complete.

.squad/agents/stringer/history.md

@@ -11,3 +11,6 @@
 ## Learnings
 
 - First session: team initialized 2026-03-05
+- **2025-07-18 — Issue #1 SDK Architecture Review:** Reviewed PRD for SourceAdapter pattern against Squad SDK (`@bradygaster/squad-sdk@0.8.24`) internals. Key finding: Squad SDK's `SkillSource`/`SkillSourceRegistry` patterns are the right structural inspiration, but the SDK itself should NOT be a runtime dependency (transitive deps too heavy, semantic mismatch between markdown skill loading and async I/O discovery). Recommended "inspired-by, not coupled-to" approach. Posted architectural review on Issue #1 with proposed interfaces, error handling strategy, and registration pattern. Decision doc written to `.squad/decisions/inbox/stringer-issue1-sdk-design.md`.
+- **SDK patterns mapped to ACCES:** `SkillSource` → `SourceAdapter`, `SkillSourceRegistry` → `SourceRegistry`, `ErrorFactory.wrap()` → `AdapterError`, `EventBus` error isolation → `Promise.allSettled()`. Registration should be explicit (not filesystem scanning). Only discovery layer needs adapter pattern — other pipeline stages stay as pure functions.
+- **Future bridge design:** A Squad SDK bridge (adapters → skills) is ~10 LOC via `defineSkill()`. Don't build until agents need to invoke discovery programmatically.