@cryptotaxi247 / SquadScope / commits / af65f5f

Plan weekly podcast generation from articles

Adds the podcast generation PRD and execution plan for SquadScope: Signal Check. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Juan Manuel Servera committed Jun 7, 2026 at 16:56 UTC af65f5fee8d5e254ee76841f22d6f4a62c87655c
3 files changed +676
.squad/agents/leela/history.md
+1
@@ -55,3 +55,4 @@
55 - Run 27056632166 post-mortems confirmed safety gates work; no-AI blocking and preservation validated in production
56 - P0 safety layer (#250/#251/#252/#253) must complete before #254 atomicity can start
57 - Issue sequencing finalized: contract/preflight (Phase 1) → atomicity/quality gates (Phase 2) → docs/evidence (Phase 3) → map/reduce stays dry-run (Phase 4)
58 +- 2026-06-07T14:46:18.154+00:00 issue #297 podcast PRD note: select Signal Check as a reviewed two-host weekly podcast; use Azure Speech for MVP TTS, Blob Storage for audio, non-blocking generation, claim-ledger safety gates, AI disclosure, and cost guardrails.
docs/PRD-podcast-generation.md new
+385
@@ -0,0 +1,385 @@
1 +# PRD: Weekly Podcast Generation from SquadScope Articles
2 +
3 +**Author:** Leela (Lead/Architect)
4 +**Date:** 2026-06-07
5 +**Status:** Draft for issue #297
6 +**Type:** Product Requirements Document
7 +**Depends on:** content/methodology/_index.md, content/privacy/_index.md, docs/analysis-spec.md, docs/pipeline-validation.md, hugo.toml
8 +
9 +---
10 +
11 +## Executive Summary
12 +
13 +SquadScope should add a weekly short-form podcast that turns each published weekly article into an 8-12 minute, two-host, scripted tech show. The recommended show is **SquadScope: Signal Check**: Host A is the Curator who explains the signal; Host B is the Skeptic who challenges hype, asks practical questions, and adds light jokes. The podcast should extend the article, not replace it, and it must keep SquadScope's evidence-first editorial standard.
14 +
15 +The MVP recommendation is:
16 +
17 +1. Generate a human-reviewed script from the already-published weekly article and its source-backed evidence.
18 +2. Use **Azure AI Speech neural TTS** for synthesis by default because SquadScope already expects Azure-friendly operations, Azure Speech supports neural voices, SSML, batch synthesis, and billable-character pricing (https://learn.microsoft.com/en-us/azure/ai-services/speech-service/text-to-speech).
19 +3. Store MP3s, transcripts, show manifests, and RSS media metadata in **Azure Blob Storage**, which is designed for unstructured objects, streaming media, and HTTP(S) access (https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction).
20 +4. Publish a podcast RSS feed at `/podcast/index.xml` and embed each episode in the matching weekly article only after gates pass.
21 +5. Keep podcast generation in a separate non-blocking workflow, `podcast-generate.yml`, triggered after weekly article publishing and by manual dispatch.
22 +
23 +Do **not** commit MP3s to git. GitHub Pages has 1 GB site/repository guidance, a 100 GB monthly soft bandwidth limit, and is not intended as free business or CDN hosting (https://docs.github.com/en/pages/getting-started-with-github-pages/github-pages-limits). Pages can host the RSS XML and player pages; object storage should host audio.
24 +
25 +---
26 +
27 +## Problem Statement
28 +
29 +SquadScope publishes weekly AI-assisted articles from GitHub and press signals. Readers who commute, exercise, or skim while working may prefer audio, but a plain article readout would be low-value. The opportunity is to create a short, dynamic, funny, source-backed podcast that makes the weekly trend analysis more approachable without weakening evidence quality.
30 +
31 +The risks are real:
32 +
33 +- Audio can make unsupported claims sound more authoritative than text.
34 +- Jokes can distort nuance or target individuals unfairly.
35 +- Synthetic voices require clear disclosure and licensing discipline.
36 +- Podcast RSS clients require strict feed/enclosure behavior.
37 +- Audio binaries can bloat the repository and exceed Pages' intended hosting model.
38 +- Monetization adds FTC disclosure, privacy, and trust obligations.
39 +
40 +This PRD defines the recommended editorial format, technical path, safety gates, monetization approach, and phased implementation plan.
41 +
42 +---
43 +
44 +## Goals and Non-Goals
45 +
46 +### Goals
47 +
48 +- Convert each published weekly article into one short podcast episode.
49 +- Make episodes useful and entertaining: dynamic, conversational, lightly funny, and technically grounded.
50 +- Preserve SquadScope's source-backed methodology, correction path, and no-paid-placement editorial stance unless explicitly changed and disclosed.
51 +- Require a claim ledger, source-backed show notes, and human review for the MVP.
52 +- Use low-cost, automatable TTS with future quality experiments isolated from MVP reliability.
53 +- Publish standards-compliant podcast RSS with stable episode identity.
54 +- Avoid blocking weekly article publishing when podcast generation fails.
55 +- Define safe monetization phases that protect reader/listener trust.
56 +
57 +### Non-Goals
58 +
59 +- Implementing code, workflows, templates, storage, or RSS generation in this issue.
60 +- Replacing the written weekly article.
61 +- Creating a daily show, long-form interview show, or news desk.
62 +- Cloning or imitating real people, Hard Fork hosts, NYT marks, jingles, segment names, or protected expression.
63 +- Committing MP3s or other generated audio binaries to git.
64 +- Launching paid ads, dynamic ad insertion, premium feeds, or analytics before privacy and disclosure work is complete.
65 +
66 +---
67 +
68 +## Audience and Use Cases
69 +
70 +| Audience | Need | Podcast value |
71 +| --- | --- | --- |
72 +| Busy developers | Understand what mattered this week without reading the whole article | 10-minute signal summary with source-backed examples |
73 +| Tech leads | Separate real adoption from hype | Skeptic host challenges weak claims and asks impact questions |
74 +| Open-source maintainers | Hear where their ecosystem sits in broader momentum | Contextualized trends, not just rankings |
75 +| Sponsors/supporters later | Reach a niche technical audience | Clear disclosed sponsorship only after trust phase |
76 +
77 +Primary listener job: "Tell me what changed in open-source and developer tools this week, what is hype, what is real, and what I should watch next."
78 +
79 +---
80 +
81 +## Editorial Product Recommendation
82 +
83 +### Show
84 +
85 +**Name:** SquadScope: Signal Check
86 +**Length:** 8-12 minutes overall; MVP automated runs target 8-10 minutes
87 +**Script length:** about 1,200-1,700 words
88 +**Format:** two-host scripted banter
89 +**Tone:** sharp, curious, evidence-first, lightly funny
90 +**Disclosure:** AI-generated voices in the first 60 seconds and in show notes
91 +
92 +### Host roles
93 +
94 +- **Host A, Curator:** Explains the signal, gives context, cites evidence, keeps the episode moving.
95 +- **Host B, Skeptic:** Challenges hype, asks "so what?", surfaces caveats, and adds jokes that compress analysis.
96 +
97 +Jokes should punch up at hype cycles, dashboard theater, benchmark theater, and vague launch language. They should not punch down at individuals, imply motives, mock protected classes, or turn uncertainty into fact.
98 +
99 +### Segment structure
100 +
101 +1. **Cold open:** One quick hook plus AI voice disclosure.
102 +2. **The Signal:** The most important repo/ecosystem movement from the article.
103 +3. **The Noise Check:** What sounds exciting but may be over-claimed.
104 +4. **The Gap:** Press narrative versus GitHub/developer evidence.
105 +5. **Receipts Round:** Fast source-backed facts, with show-note citations.
106 +6. **Week Ahead:** What to watch next week.
107 +7. **Outro:** Correction path, article link, and disclosure reminder.
108 +
109 +### Similarity guardrail
110 +
111 +The show may use broad conversational tech-podcast energy, but it must not copy Hard Fork/NYT names, segment labels, jingles, host identities, recurring bits, phrasing, or trade dress. "Signal Check" and the segments above are SquadScope-specific.
112 +
113 +---
114 +
115 +## Article-to-Episode Workflow
116 +
117 +```text
118 +published weekly article
119 + -> claim and source extraction
120 + -> claim ledger
121 + -> episode outline
122 + -> two-host conversational script
123 + -> citation and fact check
124 + -> editorial/safety review
125 + -> final script
126 + -> TTS synthesis
127 + -> ffmpeg post-process
128 + -> upload audio/transcript/manifest to Blob Storage
129 + -> update podcast RSS
130 + -> embed episode in weekly article
131 +```
132 +
133 +### Required artifacts per episode
134 +
135 +- `episode_manifest.json`: week, article URL, article hash, script prompt version, voice config hash, TTS provider, duration, file length, cost, license/disclosure status, publish status.
136 +- `claim_ledger.json`: every substantive claim, source URL, article paragraph/source, support status, and reviewer decision.
137 +- `script.md`: final reviewed script.
138 +- `transcript.txt` or `transcript.md`: public transcript generated from the final script.
139 +- `show_notes.md`: article link, source URLs, AI disclosure, corrections link, sponsor/affiliate disclosures if any.
140 +- `episode.mp3`: hosted in Blob Storage, not git.
141 +
142 +If future implementation stores manifests under `data/`, `hugo.toml` must add explicit module mounts because this repo uses custom data mounts.
143 +
144 +---
145 +
146 +## Options Considered
147 +
148 +### Editorial format options
149 +
150 +| Option | Pros | Cons | Decision |
151 +| --- | --- | --- | --- |
152 +| Single-host article readout | Simplest, cheapest, lowest editorial transformation | Boring; weak differentiation; less funny | Reject for MVP |
153 +| Two-host scripted show | Dynamic, clear roles, good for hype checks and jokes | Requires stronger script review | **Select** |
154 +| Fully improvised AI hosts | Fast, possibly lively | High risk of unsupported claims, inconsistent tone | Reject |
155 +| Human-recorded show | Highest authenticity | More operational burden; harder weekly cadence | Defer |
156 +
157 +### TTS provider options
158 +
159 +| Option | Pros | Cons | Decision |
160 +| --- | --- | --- | --- |
161 +| Azure AI Speech neural TTS | Mature SDK/REST, neural voices, SSML, batch synthesis, enterprise auth, billable characters (https://learn.microsoft.com/en-us/azure/ai-services/speech-service/text-to-speech) | Voice quality may be less expressive than newest generative voices | **Default MVP** |
162 +| Azure OpenAI voices via Azure Speech | Higher-quality experiment path, Azure operational surface, OpenAI voices/formats with SSML differences (https://learn.microsoft.com/en-us/azure/ai-services/speech-service/openai-voices) | Availability/format differences; should not block MVP | Experiment after MVP |
163 +| OpenAI `gpt-4o-mini-tts` | Strong controllability and built-in voices; docs require disclosure that the voice is AI-generated (https://developers.openai.com/api/docs/guides/text-to-speech) | Another provider/privacy path; commercial terms must be reviewed | Experiment after MVP |
164 +| MAI Voice or other providers | Potential quality upside | Unknown licensing/availability/cost in this repo | Research later |
165 +| Human narration | Best disclosure simplicity | Cost and cadence burden | Defer |
166 +
167 +### Hosting options
168 +
169 +| Option | Pros | Cons | Decision |
170 +| --- | --- | --- | --- |
171 +| Commit MP3s to git/Pages | Very simple URLs | Bloats repo; Pages limits; not CDN/business hosting (https://docs.github.com/en/pages/getting-started-with-github-pages/github-pages-limits) | Reject |
172 +| Azure Blob Storage | Designed for unstructured data, audio/video streaming, HTTP(S) access (https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) | Requires storage account/secrets/CORS/headers | **Select** |
173 +| External podcast host | Turnkey analytics/distribution | Cost, lock-in, privacy review | Defer |
174 +| CDN in front of Blob | Better scaling | Not needed for MVP | Optional later |
175 +
176 +---
177 +
178 +## Technical Requirements
179 +
180 +### Generation workflow
181 +
182 +- Add a future separate workflow: `.github/workflows/podcast-generate.yml`.
183 +- Trigger modes:
184 + - `workflow_run` after successful weekly article publish.
185 + - `workflow_dispatch` with selected week and optional dry-run flag.
186 +- Podcast failures must not block article publishing.
187 +- Manual reruns must be idempotent.
188 +
189 +### Idempotency key
190 +
191 +Episode generation identity is:
192 +
193 +```text
194 +week + article_hash + script_prompt_version + voice_config_hash
195 +```
196 +
197 +If the key is unchanged, reruns should reuse the existing reviewed script/audio unless explicitly forced. If the article changes materially, regenerate the claim ledger and require review again.
198 +
199 +### Audio requirements
200 +
201 +- Format: MP3.
202 +- MIME type: `audio/mpeg`.
203 +- Channels: mono.
204 +- Sample rate: 44.1 kHz.
205 +- Bitrate: 64-96 kbps.
206 +- Duration: max 10 minutes for MVP unless manually approved.
207 +- Size: target under 10 MB.
208 +- Loudness: normalize around -16 LUFS.
209 +- Post-processing: use `ffmpeg` for normalization, metadata, and deterministic output checks.
210 +
211 +### RSS requirements
212 +
213 +Apple's podcast requirements include RSS 2.0, a public feed, correct enclosure URL/length/type, stable GUIDs, RFC 2822 `pubDate`, ASCII URLs, and server support for HEAD and byte-range requests (https://podcasters.apple.com/support/823-podcast-requirements). MVP RSS must include:
214 +
215 +- `/podcast/index.xml` generated from manifests.
216 +- One stable GUID per episode.
217 +- `enclosure` with public HTTPS URL, exact byte length, and `audio/mpeg` type.
218 +- RFC 2822 publication date.
219 +- ASCII-only filenames and URLs.
220 +- Feed/image metadata ready for podcast directories.
221 +- Validation that the audio endpoint supports `HEAD` and byte-range requests before publishing.
222 +
223 +### Cost controls
224 +
225 +Expected scripts are about 4,500-9,000 billable characters for 5-10 minutes, which keeps Azure Speech neural TTS and likely OpenAI/Azure OpenAI mini TTS at cents-level per episode, depending on provider, region, and free allowance. Annual weekly TTS should likely stay under $10, but operations must track actual costs.
226 +
227 +MVP guardrails:
228 +
229 +- Max 5 episodes per month.
230 +- Max $5/month TTS budget.
231 +- Max 10 minutes per episode.
232 +- Cost ledger entry per episode.
233 +- Workflow fails closed before synthesis when limits would be exceeded.
234 +
235 +---
236 +
237 +## Safety, Legal, and Editorial Gates
238 +
239 +### Hard launch gates
240 +
241 +No public episode may ship unless all are true:
242 +
243 +1. AI voice disclosure appears in the first 60 seconds and show notes. OpenAI's TTS guide explicitly requires clear disclosure that TTS voice is AI-generated and not human (https://developers.openai.com/api/docs/guides/text-to-speech).
244 +2. Paid/commercial-use voice license is documented for the selected provider and voices.
245 +3. No real-person voice cloning, no celebrity/podcast-host imitation, and no Hard Fork/NYT marks or copied expression.
246 +4. Music/SFX are absent or licensed for commercial podcast use, with license recorded.
247 +5. Human script review is complete before synthesis for MVP.
248 +6. Claim ledger shows every factual claim is supported or removed.
249 +7. Show notes include source URLs and corrections link.
250 +8. No unsupported facts, no defamatory motive claims, and no fake sponsorship language.
251 +9. Sponsorship/affiliate disclosures appear before any sponsor or affiliate segment.
252 +10. Privacy policy is updated before using voice providers, podcast analytics, ad tech, or payment redirects.
253 +11. GDPR/cookie consent covers non-essential podcast analytics before analytics tags or third-party players are enabled.
254 +
255 +### FTC and monetization compliance
256 +
257 +FTC endorsement guidance requires endorsements and ads to be honest, not misleading, and to disclose material connections clearly and conspicuously (https://www.ftc.gov/business-guidance/resources/ftcs-endorsement-guides-what-people-are-asking). Therefore:
258 +
259 +- Sponsor segments must be labeled before the segment starts.
260 +- Affiliate links must be disclosed near the link and in show notes.
261 +- Hosts must not claim personal use or endorsement unless true.
262 +- Sponsored influence must not affect repo selection/ranking unless the entire product strategy changes and is disclosed.
263 +
264 +### Privacy requirements
265 +
266 +Before launch with production providers, update `content/privacy/_index.md` to document:
267 +
268 +- Voice provider(s), data sent, retention, and region if configurable.
269 +- Audio hosting provider and logs.
270 +- Podcast analytics vendors, if any.
271 +- Whether IP/user-agent data is processed by embedded players.
272 +- Payment processors for donations/premium offerings.
273 +
274 +SquadScope should not store payment data. Use Stripe, PayPal, Ko-fi, Patreon, or similar redirects if monetization needs payment handling.
275 +
276 +---
277 +
278 +## Monetization Roadmap
279 +
280 +### Phase 1: Audience and trust
281 +
282 +- Keep episodes free.
283 +- Add Ko-fi/Patreon/support links only after privacy copy is updated.
284 +- Consider newsletter sponsorship if clearly disclosed.
285 +- Allow affiliate links only when directly relevant and disclosed.
286 +- No dynamic ad insertion.
287 +
288 +### Phase 2: Ads with controls
289 +
290 +- Add host-read sponsor spots or dynamic ad insertion only after listener traction, privacy review, and disclosure templates exist.
291 +- Website ads require cookie/consent review before activation.
292 +- Maintain a sponsor policy: no paid influence over article ranking or episode claims.
293 +
294 +### Phase 3: Premium and events
295 +
296 +- Premium feed, sponsored deep dives, or live events can be explored after the core feed has reliable cadence and listener metrics.
297 +- Premium feeds require authentication/payment provider design and privacy review.
298 +
299 +---
300 +
301 +## MVP Scope
302 +
303 +### In scope
304 +
305 +- One episode per weekly article.
306 +- Two-host script generated from article plus existing evidence artifacts.
307 +- Claim ledger and source-backed show notes.
308 +- Human review before synthesis.
309 +- Azure AI Speech neural TTS.
310 +- MP3 post-processing and Blob Storage hosting.
311 +- Podcast RSS feed and weekly article embed.
312 +- AI voice disclosure and correction path.
313 +- Cost ledger and monthly budget guardrail.
314 +- Manual dispatch and post-publish workflow trigger.
315 +
316 +### Out of scope for MVP
317 +
318 +- Dynamic ad insertion.
319 +- Premium/private feeds.
320 +- Real-time/daily episodes.
321 +- Multiple languages.
322 +- Listener analytics beyond basic hosting logs, unless privacy/consent work is done.
323 +- Fully automated publish without human review.
324 +- Voice cloning or real-person mimicry.
325 +- CDN optimization.
326 +
327 +---
328 +
329 +## Acceptance Criteria
330 +
331 +### Product acceptance
332 +
333 +- A reviewer can listen to a generated episode and map every substantive factual claim to the article, claim ledger, or cited source.
334 +- Episode length fits the 8-12 minute show format, and automated MVP runs are no more than 10 minutes unless manually overridden.
335 +- The show sounds distinct from copied podcasts and uses the approved `Signal Check` structure.
336 +- Jokes clarify or compress analysis without adding unsupported claims or targeting individuals unfairly.
337 +- AI voice disclosure is audible in the first 60 seconds and visible in show notes.
338 +- Corrections path is present in show notes and article embed.
339 +
340 +### Technical acceptance
341 +
342 +- Podcast workflow can be rerun for a selected week without duplicate episodes.
343 +- Article publishing succeeds even if podcast generation fails.
344 +- MP3 is hosted outside git, under the size/duration/audio constraints.
345 +- RSS validates against Apple-style requirements: public RSS 2.0, stable GUID, enclosure URL/length/type, RFC 2822 date, ASCII URL, HEAD and byte-range support (https://podcasters.apple.com/support/823-podcast-requirements).
346 +- Cost ledger records provider, character count, duration, estimated/actual cost, and monthly budget status.
347 +- Secrets are not logged or committed.
348 +
349 +### Safety acceptance
350 +
351 +- Human reviewer approval is recorded before synthesis.
352 +- Provider voice license and AI disclosure are documented.
353 +- No real-person voice cloning or protected podcast imitation occurs.
354 +- Sponsorship/affiliate text, if present, is disclosed before the relevant segment.
355 +- Privacy policy changes are merged before production analytics/providers beyond current hosting are enabled.
356 +
357 +---
358 +
359 +## Implementation Phases
360 +
361 +1. **Design and contracts:** Define manifest, claim ledger, show notes, RSS fields, storage naming, and review statuses.
362 +2. **Script generation dry run:** Generate script/ledger/show notes from existing weekly articles without TTS or publishing.
363 +3. **TTS proof of concept:** Synthesize reviewed scripts with Azure Speech in a private artifact path; measure cost, duration, and quality.
364 +4. **Audio hosting and RSS:** Upload approved MP3s to Blob Storage, generate `/podcast/index.xml`, and validate enclosures.
365 +5. **Article embed:** Add a Hugo partial/shortcode or content data path to embed the latest episode on weekly articles.
366 +6. **MVP launch:** Enable non-blocking post-publish podcast workflow with human review gate.
367 +7. **Quality experiments:** Compare Azure OpenAI/OpenAI `gpt-4o-mini-tts` or MAI Voice against Azure Speech after MVP reliability is proven.
368 +8. **Monetization experiments:** Add support/donation links first; defer ads/premium until disclosure, privacy, and audience metrics justify them.
369 +
370 +---
371 +
372 +## Open Questions
373 +
374 +- Which Azure region and Speech resource should be used for production?
375 +- Which two neural voices best represent Curator and Skeptic while avoiding real-person mimicry?
376 +- Should script review happen through a GitHub PR, issue checklist, environment approval, or repository artifact approval file?
377 +- Should RSS be generated by Hugo from data files or by a standalone script that writes static XML?
378 +- What public podcast cover art should be used, and does it require a new design asset?
379 +- What is the minimum listener metric needed before monetization moves beyond donations?
380 +
381 +---
382 +
383 +## Decision
384 +
385 +Proceed with a docs-only design now. For implementation, build **SquadScope: Signal Check** as a human-reviewed, source-backed, two-host weekly podcast using Azure AI Speech neural TTS by default, Blob Storage for audio, a separate non-blocking generation workflow, and strict disclosure/safety/cost gates. Defer higher-quality TTS experiments, analytics, ads, premium feeds, and full automation until the MVP proves reliable and trustworthy.
docs/podcast-generation-plan.md new
+290
@@ -0,0 +1,290 @@
1 +# Podcast Generation Execution Plan
2 +
3 +**Issue:** #297
4 +**Date:** 2026-06-07
5 +**Lead:** Leela
6 +**Companion PRD:** docs/PRD-podcast-generation.md
7 +
8 +---
9 +
10 +## Recommendation Snapshot
11 +
12 +Build **SquadScope: Signal Check**, an 8-12 minute weekly two-host podcast generated from the published weekly article; automated MVP runs should target 8-10 minutes to honor the cost guardrail. Use Azure AI Speech neural TTS for MVP, Azure Blob Storage for MP3s/transcripts/manifests, and a separate non-blocking `podcast-generate.yml` workflow. Require claim ledger, source-backed show notes, AI voice disclosure, human review, cost guardrails, and RSS validation before public publish.
13 +
14 +Key references: Azure Speech TTS (https://learn.microsoft.com/en-us/azure/ai-services/speech-service/text-to-speech), Azure Blob Storage (https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction), GitHub Pages limits (https://docs.github.com/en/pages/getting-started-with-github-pages/github-pages-limits), Apple podcast requirements (https://podcasters.apple.com/support/823-podcast-requirements), OpenAI TTS disclosure guidance (https://developers.openai.com/api/docs/guides/text-to-speech), FTC endorsement guidance (https://www.ftc.gov/business-guidance/resources/ftcs-endorsement-guides-what-people-are-asking).
15 +
16 +---
17 +
18 +## Guiding Constraints
19 +
20 +- Do not commit MP3s or generated audio binaries to git.
21 +- Podcast failures must not block weekly article publishing.
22 +- MVP generation must require human script review before TTS.
23 +- Every substantive claim must be source-backed in a claim ledger.
24 +- Disclose AI-generated voices in the first 60 seconds and in show notes.
25 +- Do not clone or mimic real people, Hard Fork hosts, NYT branding, segment names, jingles, or phrasing.
26 +- Keep MVP to max 5 episodes/month, max $5/month TTS, and max 10 minutes/episode.
27 +- If new Hugo data paths are added, update `hugo.toml` module mounts explicitly.
28 +- Update privacy policy before adding voice providers, podcast analytics, payment providers, or non-essential tracking.
29 +
30 +---
31 +
32 +## Target Architecture
33 +
34 +```text
35 +crawl-and-publish.yml publishes weekly article
36 + -> podcast-generate.yml starts after success or manual dispatch
37 + -> load content/weekly/YYYY/Www.md and source artifacts
38 + -> compute article hash and idempotency key
39 + -> extract claims and citations
40 + -> generate outline, script, show notes, transcript
41 + -> human review gate
42 + -> Azure Speech TTS
43 + -> ffmpeg normalize/transcode
44 + -> upload MP3/transcript/manifest to Azure Blob Storage
45 + -> generate/update /podcast/index.xml
46 + -> embed episode in weekly article or data-driven episode block
47 +```
48 +
49 +Idempotency key:
50 +
51 +```text
52 +week + article_hash + script_prompt_version + voice_config_hash
53 +```
54 +
55 +---
56 +
57 +## Phase 0: Product and Contract Finalization
58 +
59 +**Goal:** Lock the product contract before implementation.
60 +
61 +### Issues
62 +
63 +1. **Define podcast artifact schemas**
64 + - Files: `episode_manifest.json`, `claim_ledger.json`, `show_notes.md`, `transcript.md`, reviewed `script.md`.
65 + - Include week, article URL, article hash, prompt version, voice config, provider, cost, duration, byte length, disclosure status, reviewer, and publish status.
66 + - Acceptance: sample schema fixtures exist and document required/optional fields.
67 +
68 +2. **Define editorial script prompt and style guide**
69 + - Use `SquadScope: Signal Check` format.
70 + - Segment order: cold open, The Signal, The Noise Check, The Gap, Receipts Round, Week Ahead, Outro.
71 + - Host A Curator, Host B Skeptic.
72 + - Acceptance: prompt requires citations, bans unsupported facts, bans copied podcast expression, and includes joke safety rules.
73 +
74 +3. **Choose review mechanism**
75 + - Options: PR-based reviewed script, GitHub environment approval, issue checklist, or signed manifest.
76 + - Recommendation: PR or issue checklist for MVP because it is auditable and easy to operate.
77 + - Acceptance: reviewer approval is machine-readable before synthesis.
78 +
79 +---
80 +
81 +## Phase 1: Script Dry Run, No Audio
82 +
83 +**Goal:** Prove articles can become safe, useful scripts before adding TTS.
84 +
85 +### Issues
86 +
87 +4. **Implement claim/source extraction**
88 + - Input: published weekly article plus available source artifacts.
89 + - Output: claim ledger with support status and source URLs.
90 + - Acceptance: unsupported claims fail the gate or are marked for removal.
91 +
92 +5. **Generate episode outline and script**
93 + - Output 1,200-1,700 word two-host script.
94 + - Include AI voice disclosure in first 60 seconds.
95 + - Keep jokes aimed at hype cycles, not individuals.
96 + - Acceptance: script passes length, segment, disclosure, and banned-phrase checks.
97 +
98 +6. **Generate show notes and transcript**
99 + - Show notes include article link, source links, AI disclosure, corrections link, and sponsorship disclosure placeholder.
100 + - Transcript is derived from final script.
101 + - Acceptance: every source URL in the ledger appears in show notes or is intentionally excluded with reason.
102 +
103 +7. **Add dry-run validation command**
104 + - Validate ASCII filenames, required fields, claim support, disclosure, script length, and no fake sponsor language.
105 + - Acceptance: command exits non-zero on missing ledger/support/disclosure.
106 +
107 +---
108 +
109 +## Phase 2: TTS Proof of Concept
110 +
111 +**Goal:** Synthesize private test episodes cheaply and repeatably.
112 +
113 +### Issues
114 +
115 +8. **Configure Azure Speech credentials and voice config**
116 + - Use repository secrets for keys/region or managed identity if available.
117 + - Document selected voices and commercial license status.
118 + - Acceptance: no secrets in logs; voice config hash included in manifest.
119 +
120 +9. **Add Azure Speech synthesis step**
121 + - Use neural TTS with SSML for two voices.
122 + - Track billable characters as Azure Speech bills by characters (https://learn.microsoft.com/en-us/azure/ai-services/speech-service/text-to-speech).
123 + - Acceptance: private MP3 artifact generated from reviewed script.
124 +
125 +10. **Post-process audio with ffmpeg**
126 + - Mono, 44.1 kHz, 64-96 kbps, `audio/mpeg`, target -16 LUFS, under 10 MB.
127 + - Acceptance: validation reports duration, loudness, sample rate, bitrate, channels, and byte length.
128 +
129 +11. **Add cost ledger and guardrails**
130 + - Track per-episode and monthly cost.
131 + - Enforce max 5 episodes/month, max $5/month, max 10 minutes.
132 + - Acceptance: workflow fails before synthesis if limits would be exceeded.
133 +
134 +---
135 +
136 +## Phase 3: Storage and RSS
137 +
138 +**Goal:** Publish standards-compliant podcast assets without bloating git.
139 +
140 +### Issues
141 +
142 +12. **Provision Azure Blob Storage path conventions**
143 + - Example: `podcast/YYYY/Www/squadscope-signal-check-YYYY-Www.mp3`.
144 + - ASCII filenames only.
145 + - Configure content type `audio/mpeg` and public or signed access strategy.
146 + - Acceptance: uploaded MP3 is reachable over HTTPS.
147 +
148 +13. **Validate HTTP serving requirements**
149 + - Apple requires public feed assets, HEAD, and byte-range support for episodes (https://podcasters.apple.com/support/823-podcast-requirements).
150 + - Acceptance: validation checks `HEAD`, `Accept-Ranges`, byte length, and content type.
151 +
152 +14. **Generate podcast RSS**
153 + - Output `/podcast/index.xml` with RSS 2.0, stable GUID, enclosure URL/length/type, RFC 2822 pubDate, title, description, show image, transcript/show-note links.
154 + - Acceptance: feed validates locally and with at least one podcast-feed validator.
155 +
156 +15. **Decide feed generation location**
157 + - Option A: Hugo template reads mounted data files.
158 + - Option B: standalone script writes static XML under `static/podcast/index.xml`.
159 + - Recommendation: start with standalone static XML for isolated MVP; revisit Hugo data if templates need richer integration.
160 + - Acceptance: no missing module mounts if data files are added.
161 +
162 +---
163 +
164 +## Phase 4: Site Integration
165 +
166 +**Goal:** Make episodes discoverable from the article and site.
167 +
168 +### Issues
169 +
170 +16. **Add article embed**
171 + - Add audio player or link block to matching weekly article after episode publish.
172 + - Include transcript, show notes, AI voice disclosure, and correction link.
173 + - Acceptance: weekly article renders without raw HTML unsafe mode changes.
174 +
175 +17. **Add podcast landing page**
176 + - Explain show format, disclosure, feed link, correction path, and methodology.
177 + - Acceptance: page builds in Hugo and links to `/podcast/index.xml`.
178 +
179 +18. **Update methodology and privacy pages**
180 + - Methodology: explain article-to-podcast transformation and safety gates.
181 + - Privacy: document voice provider, Blob hosting logs, analytics/payment providers if used.
182 + - Acceptance: public docs match actual providers and data flows.
183 +
184 +---
185 +
186 +## Phase 5: Launch Controls
187 +
188 +**Goal:** Enable reliable weekly operation.
189 +
190 +### Issues
191 +
192 +19. **Create `podcast-generate.yml`**
193 + - Trigger on successful article publish via `workflow_run` and manual `workflow_dispatch` for selected week.
194 + - Must be non-blocking relative to `crawl-and-publish.yml`.
195 + - Acceptance: failed podcast run does not fail or roll back article publishing.
196 +
197 +20. **Add manual approval gate**
198 + - Require reviewed script status before TTS.
199 + - Acceptance: unreviewed scripts stop before synthesis.
200 +
201 +21. **Add observability**
202 + - Log episode key, provider, duration, cost estimate, byte length, validation results, and publish URL.
203 + - Do not log secrets or full provider credentials.
204 + - Acceptance: operator can diagnose failures from workflow summary.
205 +
206 +22. **Pilot launch with one back-catalog episode**
207 + - Generate one recent weekly episode as a pilot.
208 + - Do not submit to directories until RSS and safety checks pass.
209 + - Acceptance: reviewer signs off on audio quality, citations, disclosure, and feed validity.
210 +
211 +---
212 +
213 +## Phase 6: Quality and Monetization Experiments
214 +
215 +**Goal:** Improve quality and revenue only after trust and reliability.
216 +
217 +### Issues
218 +
219 +23. **Compare higher-quality TTS providers**
220 + - Test Azure OpenAI voices via Azure Speech (https://learn.microsoft.com/en-us/azure/ai-services/speech-service/openai-voices) and OpenAI `gpt-4o-mini-tts` (https://developers.openai.com/api/docs/guides/text-to-speech) against Azure Speech baseline.
221 + - Acceptance: compare cost, license/disclosure, latency, voice quality, SSML/control, and privacy terms.
222 +
223 +24. **Add support/donation links**
224 + - Ko-fi/Patreon/PayPal/Stripe redirects only; do not store payment data.
225 + - Acceptance: privacy page and disclosure copy are updated.
226 +
227 +25. **Define sponsorship policy**
228 + - FTC requires material connections to be disclosed clearly and conspicuously (https://www.ftc.gov/business-guidance/resources/ftcs-endorsement-guides-what-people-are-asking).
229 + - Acceptance: sponsor copy template discloses before sponsor segment and forbids sponsor influence over rankings.
230 +
231 +26. **Evaluate premium feed or dynamic ads**
232 + - Defer until audience metrics justify complexity.
233 + - Acceptance: privacy, consent, payment, RSS auth, and disclosure designs are approved before implementation.
234 +
235 +---
236 +
237 +## Suggested Issue Breakdown
238 +
239 +| Priority | Issue title | Owner | Depends on |
240 +| --- | --- | --- | --- |
241 +| P0 | Define podcast artifact schemas and idempotency key | Leela/Bender | PRD approval |
242 +| P0 | Define Signal Check editorial prompt and safety style guide | Farnsworth/Hermes | PRD approval |
243 +| P0 | Implement claim ledger extraction and validation | Farnsworth/Fry | schemas |
244 +| P0 | Generate dry-run scripts/show notes/transcripts | Farnsworth | prompt, ledger |
245 +| P0 | Add human review gate for podcast scripts | Hermes/Leela | dry run |
246 +| P1 | Add Azure Speech synthesis proof of concept | Bender | review gate |
247 +| P1 | Add ffmpeg audio validation and normalization | Bender/Fry | TTS POC |
248 +| P1 | Add cost ledger and monthly guardrails | Hermes/Bender | TTS POC |
249 +| P1 | Upload podcast assets to Azure Blob Storage | Bender | audio validation |
250 +| P1 | Generate and validate podcast RSS | Bender/Fry | storage |
251 +| P1 | Add weekly article episode embed | Bender | RSS/storage |
252 +| P1 | Update methodology and privacy pages for podcast launch | Hermes/Leela | provider choices |
253 +| P2 | Pilot one back-catalog episode | Leela/Farnsworth | P1 complete |
254 +| P2 | Evaluate OpenAI/Azure OpenAI/MAI voice quality | Bender | MVP pilot |
255 +| P2 | Add support/donation links | Hermes | privacy update |
256 +| P3 | Evaluate ads, premium feed, or live events | Hermes/Leela | audience metrics |
257 +
258 +---
259 +
260 +## Phase Acceptance Criteria
261 +
262 +- Phase 0 is complete when schemas, prompts, and review status are documented well enough for implementation without product ambiguity.
263 +- Phase 1 is complete when a weekly article can produce a reviewed script, transcript, show notes, and claim ledger without audio synthesis.
264 +- Phase 2 is complete when a reviewed script can synthesize a private validated MP3 under duration, size, loudness, and cost limits.
265 +- Phase 3 is complete when storage and RSS validation prove public episode delivery meets podcast-client requirements.
266 +- Phase 4 is complete when the article embed, landing page, methodology, and privacy updates accurately describe the launched experience.
267 +- Phase 5 is complete when the non-blocking workflow can publish a pilot episode and leave article publishing unaffected by podcast failures.
268 +
269 +## Validation Checklist for First Public Episode
270 +
271 +- [ ] Script is 1,200-1,700 words and target duration fits the 8-12 minute format, with automated MVP output at or below 10 minutes.
272 +- [ ] AI voice disclosure is in first 60 seconds and show notes.
273 +- [ ] Claim ledger has no unsupported public claims.
274 +- [ ] Human reviewer approved script before synthesis.
275 +- [ ] Provider voice license is documented.
276 +- [ ] No real-person voice cloning or protected podcast imitation.
277 +- [ ] No fake sponsor language.
278 +- [ ] Show notes include source URLs and corrections link.
279 +- [ ] MP3 is mono, 44.1 kHz, 64-96 kbps, `audio/mpeg`, normalized near -16 LUFS, and under 10 MB.
280 +- [ ] Audio is hosted outside git.
281 +- [ ] RSS includes stable GUID, enclosure URL/length/type, RFC 2822 pubDate, and ASCII URLs.
282 +- [ ] Audio endpoint supports HEAD and byte-range requests.
283 +- [ ] Cost ledger is updated and monthly guardrails pass.
284 +- [ ] Privacy and methodology pages match actual providers and analytics.
285 +
286 +---
287 +
288 +## Definition of Done for MVP
289 +
290 +The MVP is done when a successful weekly article can trigger a non-blocking podcast workflow that creates a reviewed, source-backed two-host episode; synthesizes it with documented Azure Speech voices; uploads validated MP3/transcript/show notes/manifests to Blob Storage; publishes a valid RSS item; embeds the episode in the article; records cost; and leaves weekly article publishing unaffected if podcast generation fails.