@cryptotaxi247 / SquadScope / commits / 8c23651

Correct podcast scope to external platform product

Reframes Podcaster as a separate product with zero impact on SquadScope publishing. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Juan Manuel Servera committed Jun 7, 2026 at 19:17 UTC 8c23651f2fd9c2969db8f9b833ab318954251026
3 files changed +441 -277
.squad/agents/leela/history.md
+2 -1
@@ -56,4 +56,5 @@
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.
59 -- 2026-06-07T15:00:15.655+00:00 issue #299 rubber-duck amendment: podcast MVP requires `podcast-review` environment approval before TTS, explicit post-publish dispatch, privacy-before-TTS, provider listening test, stable RSS enclosure URLs, Hugo shortcode embed, voice-only MVP, and total cost guardrails.
59 +- 2026-06-07T15:00:15.655+00:00 issue #299 rubber-duck amendment: podcast MVP required `podcast-review` environment approval before TTS, explicit post-publish dispatch, privacy-before-TTS, provider listening test, stable RSS enclosure URL review, Hugo website integration review, voice-only MVP, and total cost guardrails; #310 later narrowed website scope to external link only.
60 +- 2026-06-07T17:04:54.240+00:00 issue #310 correction: Podcaster is a future sister product/tool, not a SquadScope website feature; SquadScope should keep only docs/contracts or harmless prototypes now, preserve zero impact on existing weekly publishing, and move implementation to a separate Podcaster project/repo before Azure resource deployment.
docs/PRD-podcast-generation.md
+217 -128
@@ -1,43 +1,52 @@
1 # PRD: Weekly Podcast Generation from SquadScope Articles
2
3 -**Author:** Leela (Lead/Architect)
4 -**Date:** 2026-06-07
5 -**Status:** Accepted / amended after rubber-duck review for issue #299
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
3 +**Author:** Leela (Lead/Architect)
4 +**Date:** 2026-06-07
5 +**Status:** Accepted / amended for issue #310 platform-podcast scope
6 +**Type:** Product Requirements Document
7 +**Depends on:** content/methodology/_index.md, content/privacy/_index.md, docs/analysis-spec.md, docs/pipeline-validation.md
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.
13 +SquadScope should enable **SquadScope: Signal Check**, an 8-12 minute weekly two-host podcast generated from the already-published weekly article. The podcast/Podcaster capability is a **sister product/tool**, not a SquadScope website feature. It should be distributed through Spotify and/or a podcast platform, not hosted inside the SquadScope website. The website MVP only adds a configurable link to the external podcast page once that page exists.
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. Run the Phase 2 TTS proof of concept before full storage/RSS build-out: compare Azure Speech Standard neural voices, Azure Speech HD/OpenAI voices in Azure if available, and OpenAI `tts-1` or `gpt-4o-mini-tts`; choose the MVP provider from a documented listening test plus cost/privacy review.
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`, started by explicit dispatch from `crawl-and-publish.yml` only after a confirmed normal publish, plus manual dispatch for operators.
17 +1. Generate a human-reviewed script, transcript, show notes, and publishing packet from the published weekly article and its source-backed evidence.
18 +2. Run the Phase 2 TTS proof of concept before production synthesis: compare Azure Speech Standard neural voices, Azure Speech HD/OpenAI voices in Azure if available, and OpenAI `tts-1` or `gpt-4o-mini-tts`; choose the MVP provider from a documented listening test plus cost/privacy review.
19 +3. Store generated MP3s and working artifacts temporarily in **Azure Blob Storage** as staging storage with retention and cleanup controls. Blob Storage is not the final public podcast host for MVP unless a later delivery decision explicitly approves it.
20 +4. Prepare a manual Spotify publishing packet for the operator: MP3, title, description, transcript/show notes, AI disclosure, sponsor/affiliate disclosures if any, source article URL, and corrections link.
21 +5. Investigate whether Spotify supports episode upload/publish automation. Initial documentation research suggests the Spotify Web API is primarily for streaming-service interactions such as metadata, playlists, playback, and user library operations, not clearly for podcast episode upload; this must be verified against Spotify for Creators and current podcast delivery docs.
22 +6. Keep SquadScope's publishing path unchanged. Any temporary workflow in this repo may only be manually invoked or emit/consume post-publish artifacts after normal publishing is complete; the production podcast generation workflow should live in the separate Podcaster project once the project boundary is defined.
23
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 +Do **not** commit MP3s to git. Do **not** build website-hosted podcast pages, audio players, article audio embeds, or a site-owned feed as MVP scope; those website-hosted consumption patterns are explicitly deferred/non-MVP. If an RSS feed exists during MVP, it is for podcast-platform ingestion or a future podcast host migration, not for SquadScope website consumption.
25
26 ---
27
28 ## Problem Statement
29
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 +SquadScope publishes weekly AI-assisted articles from GitHub and press signals. Some users may prefer an audio product they can follow in their podcast app. 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.
31
31 -The risks are real:
32 +The clarified product scope changes delivery:
33 +
34 +- The podcast is not hosted in the same SquadScope website.
35 +- Spotify or another podcast platform is the launch destination.
36 +- Initial Spotify publishing is manual.
37 +- Automation feasibility must be researched before promising automatic publish.
38 +- The website only links out to the external podcast/platform page.
39 +- The current weekly crawl/analyze/generate/deploy publishing process must not be modified, gated, delayed, or made dependent on podcast generation.
40 +
41 +Key risks:
42
43 - Audio can make unsupported claims sound more authoritative than text.
44 - Jokes can distort nuance or target individuals unfairly.
45 - 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.
46 +- Platform publishing workflows may require manual steps or third-party hosting APIs.
47 +- Azure podcast resources belong to the future Podcaster project, not the SquadScope publishing runtime, unless a later architecture decision explicitly says otherwise.
48 +- Temporary audio artifacts need retention, cleanup, and access controls.
49 +- Monetization adds FTC disclosure, privacy, and trust obligations for both podcast and website.
50
51 ---
52
@@ -46,22 +55,28 @@ This PRD defines the recommended editorial format, technical path, safety gates,
55 ### Goals
56
57 - Convert each published weekly article into one short podcast episode.
49 -- Make episodes useful and entertaining: dynamic, conversational, lightly funny, and technically grounded.
58 +- Treat Podcaster as a separate sister product/tool with Spotify/podcast-platform publishing as the target.
59 - 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 selected by an early Phase 2 listening-test comparison before storage/RSS implementation.
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.
60 +- Require a claim ledger, source-backed show notes, publishing packet, and human review for MVP.
61 +- Use low-cost, automatable TTS selected by an early listening-test comparison.
62 +- Store generated audio temporarily in Azure Blob Storage with retention and cleanup.
63 +- Support manual Spotify publishing first, then research and design automation if available.
64 +- Limit website integration to a configurable external podcast link.
65 +- Preserve zero impact on existing weekly crawl/analyze/generate/deploy behavior.
66 +- Define safe monetization phases for podcast and website.
67
68 ### Non-Goals
69
59 -- Implementing code, workflows, templates, storage, or RSS generation in this issue.
70 +- Implementing code, workflows, templates, storage, publishing integrations, Azure infrastructure, or RSS generation in this issue.
71 +- Hosting the podcast inside the SquadScope website.
72 +- Website-hosted audio players, article audio embeds, Hugo podcast shortcodes, or podcast landing/player pages are non-MVP/deferred.
73 +- Publishing a SquadScope-site-owned `/podcast/index.xml` feed for listener consumption is non-MVP/deferred.
74 - Replacing the written weekly article.
75 - Creating a daily show, long-form interview show, or news desk.
76 - Cloning or imitating real people, Hard Fork hosts, NYT marks, jingles, segment names, or protected expression.
77 - Committing MP3s or other generated audio binaries to git.
78 - Launching paid ads, dynamic ad insertion, premium feeds, or analytics before privacy and disclosure work is complete.
79 +- Changing the current weekly crawl/analyze/generate/deploy pipeline, publish manifests, article publishing gates, or critical-path behavior for podcast needs.
80
81 ---
82
@@ -72,7 +87,7 @@ This PRD defines the recommended editorial format, technical path, safety gates,
87 | Busy developers | Understand what mattered this week without reading the whole article | 10-minute signal summary with source-backed examples |
88 | Tech leads | Separate real adoption from hype | Skeptic host challenges weak claims and asks impact questions |
89 | 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 |
90 +| Sponsors/supporters later | Reach a niche technical audience | Clear disclosed support/sponsorship only after trust phase |
91
92 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."
93
@@ -82,12 +97,12 @@ Primary listener job: "Tell me what changed in open-source and developer tools t
97
98 ### Show
99
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
100 +**Name:** SquadScope: Signal Check
101 +**Length:** 8-12 minutes overall; MVP automated runs target 8-10 minutes
102 +**Script length:** about 1,200-1,700 words
103 +**Format:** two-host scripted banter
104 +**Tone:** sharp, curious, evidence-first, lightly funny
105 +**Disclosure:** AI-generated voices in the first 60 seconds and in show notes/publishing description
106
107 ### Host roles
108
@@ -104,7 +119,7 @@ Jokes should punch up at hype cycles, dashboard theater, benchmark theater, and
119 4. **The Gap:** Press narrative versus GitHub/developer evidence.
120 5. **Receipts Round:** Fast source-backed facts, with show-note citations.
121 6. **Week Ahead:** What to watch next week.
107 -7. **Outro:** Correction path, article link, and disclosure reminder.
122 +7. **Outro:** Correction path, article link, external podcast follow prompt, and disclosure reminder.
123
124 ### Similarity guardrail
125
@@ -112,40 +127,53 @@ The show may use broad conversational tech-podcast energy, but it must not copy
127
128 ---
129
130 +### Product boundary
131 +
132 +Podcaster is a sister product/tool that consumes SquadScope outputs; it is not a SquadScope website feature. SquadScope remains responsible for publishing the weekly article and, at most, exposing stable post-publish artifacts such as article URL, article content, source artifact references, or a manifest. Podcaster is responsible for script generation, TTS, audio staging, platform publishing packets, Azure resources, podcast operations, and any future podcast workflow once separated.
133 +
134 +### Zero-impact publishing principle
135 +
136 +Podcast work must have zero impact on existing publishing:
137 +
138 +- No changes to the current weekly crawl/analyze/generate/deploy behavior.
139 +- No gating, delaying, rolling back, or replacing article publishing because of podcast generation.
140 +- No changes to existing publish manifests for podcast-only metadata unless a separate backward-compatible contract is approved.
141 +- No audio generation, TTS provider calls, Blob uploads, or podcast validation inside the article publishing critical path.
142 +- No requirement that podcast artifacts exist before an article is considered published.
143 +- Any future SquadScope workflow may only emit a post-publish event/artifact or be manually invoked; the podcast generation workflow should live in Podcaster once the project is separated.
144 +
145 +---
146 +
147 ## Article-to-Episode Workflow
148
149 ```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 - -> GitHub Environment podcast-review approval
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
150 +SquadScope normal weekly publish completes unchanged
151 + -> SquadScope exports stable post-publish article URL/content/artifact manifest
152 + -> Podcaster consumes the artifact asynchronously or via manual invocation
153 + -> Podcaster performs claim and source extraction
154 + -> Podcaster creates claim ledger, outline, two-host script, show notes, transcript, and publishing packet
155 + -> Podcaster review gate approves script package
156 + -> Podcaster performs TTS synthesis and ffmpeg post-process outside SquadScope critical path
157 + -> Podcaster uploads MP3/transcript/manifest to its temporary Azure Blob staging
158 + -> operator manually publishes to Spotify or selected podcast platform
159 + -> SquadScope website external podcast link is updated only when a platform page exists
160 ```
161
162 ### Required artifacts per episode
163
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.
164 +- `episode_manifest.json`: week, article URL, article/content/artifact manifest reference, article hash, script prompt version, voice config hash, TTS provider, duration, file length, cost, license/disclosure status, staging storage URI, retention expiry, reviewer, and publish status.
165 - `claim_ledger.json`: every substantive claim derived from the published article, source URL, article paragraph/source, validation status against existing analysis/publish artifacts where available, support status, and reviewer decision.
166 - `script.md`: final reviewed script.
138 -- `transcript.txt` or `transcript.md`: public transcript generated from the final script.
167 +- `transcript.txt` or `transcript.md`: transcript generated from the final script.
168 - `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.
169 +- `publishing_packet.md` or equivalent operator summary: MP3 path, title, description, transcript/show notes, disclosures, source article URL, corrections link, and manual publish checklist.
170 +- `episode.mp3`: temporary staging artifact in Azure Blob Storage, not git.
171
172 +If a temporary prototype stores docs or sample manifests under `data/`, `hugo.toml` must add explicit module mounts because this repo uses custom data mounts. Production podcast manifests should belong to Podcaster or the selected podcast platform/host, not SquadScope's existing publish manifests.
173
174 ### Human review mechanism
175
147 -MVP uses a single concrete review mechanism: the GitHub Environment `podcast-review` with required reviewers. `podcast-generate.yml` uploads the generated script package as workflow artifacts, then pauses before any non-dry-run TTS call by entering the `podcast-review` environment. TTS cannot proceed until the environment approval is granted. Reviewers inspect `script.md`, `claim_ledger.json`, `show_notes.md`, `transcript.md`, and `episode_manifest.json`, with attention to source support, disclosure, tone, privacy readiness, and budget status.
148 -
176 +MVP uses a concrete review mechanism before synthesis. If a temporary prototype remains in this repo, the GitHub Environment `podcast-review` can pause that manually invoked/post-publish workflow before any non-dry-run TTS call. Once separated, Podcaster should own the equivalent review gate in its own deployment lifecycle. TTS cannot proceed until approval is granted. Reviewers inspect `script.md`, `claim_ledger.json`, `show_notes.md`, `transcript.md`, `publishing_packet.md`, and `episode_manifest.json`, with attention to source support, disclosure, tone, privacy readiness, budget status, and manual publishing readiness.
177
178 ---
179
@@ -170,14 +198,28 @@ MVP uses a single concrete review mechanism: the GitHub Environment `podcast-rev
198 | MAI Voice or other providers | Potential quality upside | Unknown licensing/availability/cost in this repo | Research later |
199 | Human narration | Best disclosure simplicity | Cost and cadence burden | Defer |
200
173 -### Hosting options
201 +### Publishing and storage options
202
203 | Option | Pros | Cons | Decision |
204 | --- | --- | --- | --- |
177 -| 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 |
178 -| 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** |
179 -| External podcast host | Turnkey analytics/distribution | Cost, lock-in, privacy review | Defer |
180 -| CDN in front of Blob | Better scaling and stable public URLs | Extra configuration | Optional later; acceptable if URLs are stable |
205 +| Commit MP3s to git/Pages | Very simple URLs | Bloats repo; not appropriate for audio product delivery | Reject |
206 +| SquadScope website podcast hosting | Full control | Contradicts clarified product scope; adds feed/player/site maintenance | Reject for MVP |
207 +| Azure Blob Storage as temporary staging | Designed for unstructured objects and workflow artifacts (https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) | Needs retention, cleanup, access controls | **Select for staging** |
208 +| Manual Spotify for Creators/platform upload | Fastest path to validate product | Operator step; no full automation | **Select for initial launch** |
209 +| Podcast host/provider RSS | Standard distribution path; may expose APIs | Cost, lock-in, privacy review | Research alongside Spotify API |
210 +| Direct Spotify/API automation | Could reduce weekly operator work | Upload/publish API support is unclear | Research before implementation |
211 +
212 +---
213 +
214 +### Architecture and repository boundary options
215 +
216 +| Option | Description | Pros | Cons | Decision |
217 +| --- | --- | --- | --- | --- |
218 +| Option A: temporary folder in this repo | Keep docs, contracts, sample artifacts, and possibly throwaway prototypes in a clearly isolated folder. | Fastest learning path; keeps article contract close to SquadScope. | Easy to blur product ownership; must not affect publishing, manifests, workflows, or deploys. | Accept only for prototypes/docs that cannot affect publishing. |
219 +| Option B: separate repo/project from the start | Create a `Podcaster` project/repo for implementation, tests, workflow, secrets, and release process. | Clean ownership; protects SquadScope publishing; easier independent roadmap. | Slight setup overhead before first prototype. | Preferred before implementation grows beyond contracts/prototypes. |
220 +| Option C: Azure-native project/resource group | Build Podcaster as its own Azure resource group/subscription boundary with IaC and independent deployment lifecycle. | Best fit for Azure Speech/Blob/identity/cost governance; clear resource ownership. | Requires infrastructure governance and cost controls up front. | Required before any Azure resource deployment. |
221 +
222 +**Recommendation:** Keep the SquadScope repo as the source of article export contracts, PRD, and planning now. Move implementation to a separate **Podcaster** project/repo before deploying Azure resources. Use a temporary folder in this repo only for prototypes that cannot affect publishing and do not add audio steps to the article critical path.
223
224 ---
225
@@ -185,11 +227,10 @@ MVP uses a single concrete review mechanism: the GitHub Environment `podcast-rev
227
228 ### Generation workflow
229
188 -- Add a future separate workflow: `.github/workflows/podcast-generate.yml`.
189 -- Trigger modes:
190 - - Preferred automated path: after `crawl-and-publish.yml` confirms a normal weekly publish, it explicitly dispatches `podcast-generate.yml` with the week, article path/URL, source run ID, publish mode, and article artifact identifiers.
191 - - `workflow_dispatch` with selected week and optional dry-run flag for operators.
192 -- Do not rely on a naive `workflow_run` trigger. If a future implementation uses `workflow_run`, it must fetch and validate the triggering run inputs/artifacts and prove the run was a normal publish before synthesis.
230 +- SquadScope must not add podcast generation to the weekly crawl/analyze/generate/deploy critical path.
231 +- SquadScope may expose a stable post-publish artifact/API/URL contract containing week, article URL/path, content or content hash, source artifact references, run ID, and publish mode after normal publishing completes.
232 +- Communication is by stable artifact, API, URL, or manual input. Podcaster must not directly mutate SquadScope publishing flow, publish manifests, article content, or deploy state.
233 +- Any future workflow that remains in SquadScope may only emit a post-publish event/artifact or be manually invoked for a prototype; production podcast generation should live in Podcaster once separated.
234 - Dry-run, candidate-only, restore, failed, or no-AI fallback replacement runs must not synthesize audio or publish podcast artifacts.
235 - Podcast failures must not block article publishing.
236 - Manual reruns must be idempotent.
@@ -216,35 +257,64 @@ If the key is unchanged, reruns should reuse the existing reviewed script/audio
257 - Loudness: normalize around -16 LUFS.
258 - Post-processing: use `ffmpeg` for normalization, metadata, and deterministic output checks.
259
219 -### RSS requirements
260 +### Integration boundary requirements
261 +
262 +- SquadScope exports article URL/content/artifact manifest after a successful normal publish.
263 +- Podcaster consumes that export asynchronously and owns all podcast-specific processing.
264 +- Integration must be additive and backward-compatible; existing publish manifests remain unchanged unless a separate contract version is approved.
265 +- The Podcaster implementation must use least-privilege access to read only the exported article/artifacts it needs.
266 +
267 +### Temporary Azure Blob Storage requirements
268 +
269 +- Use Podcaster-owned Blob Storage for staging generated MP3s, transcripts, manifests, and publishing packets.
270 +- Apply least-privilege access; public anonymous read is not required for MVP staging.
271 +- Configure retention/cleanup so generated audio is removed after publishing is confirmed or after a defined expiry.
272 +- Do not use expiring staging URLs in any public podcast feed or platform field.
273 +- Record staging path and expiry in `episode_manifest.json`.
274 +- If a future RSS/provider integration needs public enclosures, make a separate delivery decision for a podcast host, provider API, or approved stable enclosure strategy.
275 +
276 +### Manual Spotify/platform publishing packet
277 +
278 +Before a human publishes the episode, the workflow must produce a packet containing:
279 +
280 +- Final MP3.
281 +- Episode title.
282 +- Episode description.
283 +- Transcript and/or show notes.
284 +- AI voice disclosure.
285 +- Sponsor, affiliate, or support disclosures, if any.
286 +- Source weekly article URL.
287 +- Corrections link.
288 +- Claim ledger and reviewer identity/time for audit.
289 +- Post-publish fields to fill in: external episode URL, platform, publish time, and corrections/update notes.
290 +
291 +### Spotify/API research requirement
292 +
293 +Create a research phase before any automated publishing implementation:
294
221 -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:
295 +1. Verify current Spotify for Creators, Spotify podcast delivery, and Spotify Web API docs.
296 +2. Confirm whether Spotify exposes an upload/publish API for podcast episodes.
297 +3. If Spotify does not support direct upload/publish automation, research podcast host/provider RSS APIs, hosting APIs, or a documented manual Spotify for Creators flow.
298 +4. Record authentication, privacy, retention, approval, rollback/correction, and rate-limit implications.
299 +5. Do not promise or build automated Spotify publishing until this research is accepted.
300
223 -- `/podcast/index.xml` generated from manifests.
224 -- One stable GUID per episode.
225 -- `enclosure` with stable public HTTPS URL, exact byte length, and `audio/mpeg` type.
226 -- RFC 2822 publication date.
227 -- ASCII-only filenames and URLs.
228 -- Feed/image metadata ready for podcast directories.
229 -- Validation that the audio endpoint supports `HEAD` and byte-range requests before publishing.
230 -- Enclosure URLs must use public anonymous Blob read access or CDN-backed stable public URLs; expiring SAS URLs are explicitly prohibited for RSS enclosures.
231 -- If MVP writes `static/podcast/index.xml`, it must not coexist ambiguously with a future Hugo `content/podcast/` section. If a Hugo podcast section is added, remove or replace static XML generation so only one feed owner exists.
301 +Caveat: initial documentation research suggests the Spotify Web API is for streaming-service interactions like metadata, playlists, playback, and library operations, not clearly podcast episode upload. This must be verified against current Spotify for Creators and podcast delivery documentation.
302
233 -### Hugo article embed
303 +### Website integration requirement
304
235 -Weekly articles must use a Hugo `podcast-episode` shortcode/partial, not raw HTML. The embed renders the audio player, transcript link, show notes link, correction path, and AI-generated voice disclosure while leaving Hugo `unsafe = false` unchanged.
305 +The SquadScope website MVP only needs a configurable link to the external podcast page once available, such as a Spotify show page or selected platform page. The link should be easy to disable until launch. No site-hosted feed, no article audio embed, and no embedded player are MVP requirements.
306
307 ### Cost controls
308
239 -Expected scripts are about 4,500-9,000 billable characters for 5-10 minutes, which keeps many TTS options at cents-level per episode, depending on provider, region, and free allowance. Operations must track total podcast cost, not just TTS: TTS, storage, egress/download bandwidth, script generation, validation, and any CDN charges. Egress may dominate if downloads grow.
309 +Expected scripts are about 4,500-9,000 billable characters for 5-10 minutes, which keeps many TTS options at cents-level per episode, depending on provider, region, and free allowance. Operations must track total podcast cost, not just TTS: TTS, storage, egress/download bandwidth if any, script generation, validation, platform/provider costs, and future CDN charges if approved.
310
311 MVP guardrails:
312
313 - Max 5 episodes per month.
244 -- Max $5/month total podcast budget for TTS, storage, egress, script generation, validation, and CDN if used.
314 +- Max $5/month total podcast budget unless manually raised.
315 - Max 10 minutes per episode.
316 - Cost ledger entry per episode with per-category estimates/actuals.
247 -- Workflow fails closed before non-dry-run synthesis or publish when limits would be exceeded.
317 +- Workflow fails closed before non-dry-run synthesis or publish-packet generation when limits would be exceeded.
318
319 ---
320
@@ -254,16 +324,16 @@ MVP guardrails:
324
325 No public episode may ship unless all are true:
326
257 -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).
327 +1. AI voice disclosure appears in the first 60 seconds and show notes/platform description. 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).
328 2. Paid/commercial-use voice license is documented for the selected provider and voices.
329 3. No real-person voice cloning, no celebrity/podcast-host imitation, and no Hard Fork/NYT marks or copied expression.
260 -4. MVP is voice-only: no music or SFX unless/until a licensed track/effect is selected and recorded in the manifest. Licensed music/SFX is a later issue with explicit acceptance criteria.
261 -5. Human script review is complete through the GitHub Environment `podcast-review` gate before synthesis for MVP.
330 +4. MVP is voice-only: no music or SFX unless/until a licensed track/effect is selected and recorded in the manifest.
331 +5. Human script review is complete through the Podcaster review gate before synthesis for MVP; a temporary in-repo prototype may use the GitHub Environment `podcast-review`.
332 6. Claim ledger shows every factual claim is supported or removed.
333 7. Show notes include source URLs and corrections link.
334 8. No unsupported facts, no defamatory motive claims, and no fake sponsorship language.
265 -9. Sponsorship/affiliate disclosures appear before any sponsor or affiliate segment.
266 -10. Privacy policy is updated before any non-dry-run TTS call or before using podcast analytics, ad tech, or payment redirects.
335 +9. Sponsorship/affiliate/support disclosures appear before any sponsor, affiliate, or paid support segment.
336 +10. Privacy policy is updated before any non-dry-run TTS call or before any future/deferred use of podcast analytics, ad tech, payment redirects, or third-party embedded players.
337 11. GDPR/cookie consent covers non-essential podcast analytics before analytics tags or third-party players are enabled.
338
339 ### FTC and monetization compliance
@@ -274,41 +344,45 @@ FTC endorsement guidance requires endorsements and ads to be honest, not mislead
344 - Affiliate links must be disclosed near the link and in show notes.
345 - Hosts must not claim personal use or endorsement unless true.
346 - Sponsored influence must not affect repo selection/ranking unless the entire product strategy changes and is disclosed.
347 +- Support/donation links must not imply editorial influence.
348
349 ### Privacy requirements
350
280 -Before Phase 2 performs any non-dry-run TTS call, update `content/privacy/_index.md` to document the selected voice-provider candidates and data flow. This privacy update is a prerequisite to Phase 2, not a launch cleanup item. Also update it before analytics, ad tech, or payment redirects are enabled to document:
351 +Before Phase 2 performs any non-dry-run TTS call, update `content/privacy/_index.md` to document the selected voice-provider candidates and data flow. This privacy update is a prerequisite to Phase 2, not a launch cleanup item. Also update it before analytics, ad tech, payment redirects, or external players are enabled to document:
352
353 - Voice provider(s), data sent, retention, and region if configurable.
283 -- Audio hosting provider and logs.
354 +- Temporary Azure Blob Storage staging, access controls, logs, and cleanup policy.
355 +- Spotify/podcast platform or host, if selected.
356 - Podcast analytics vendors, if any.
285 -- Whether IP/user-agent data is processed by embedded players.
357 +- Whether IP/user-agent data is processed by external podcast links, widgets, or players.
358 - Payment processors for donations/premium offerings.
359
288 -SquadScope should not store payment data. Use Stripe, PayPal, Ko-fi, Patreon, or similar redirects if monetization needs payment handling.
360 +SquadScope should not store payment data. Use Stripe, PayPal, Ko-fi, Patreon, GitHub Sponsors, or similar redirects if monetization needs payment handling.
361
362 ---
363
364 ## Monetization Roadmap
365
294 -### Phase 1: Audience and trust
366 +### Phase 1: Manual/support-first launch
367
368 - Keep episodes free.
297 -- Add Ko-fi/Patreon/support links only after privacy copy is updated.
298 -- Consider newsletter sponsorship if clearly disclosed.
299 -- Allow affiliate links only when directly relevant and disclosed.
300 -- No dynamic ad insertion.
369 +- Launch manually on Spotify or the selected platform while audience and quality are validated.
370 +- Add optional website support links only after privacy copy and disclosure language are updated.
371 +- Consider GitHub Sponsors, Ko-fi, Patreon, PayPal, Stripe, or newsletter/support redirects; do not store payment data in SquadScope.
372 +- Make clear that support does not influence article ranking, claims, or episode coverage.
373
302 -### Phase 2: Ads with controls
374 +### Phase 2: Sponsorships with controls
375
304 -- Add host-read sponsor spots or dynamic ad insertion only after listener traction, privacy review, and disclosure templates exist.
305 -- Website ads require cookie/consent review before activation.
306 -- Maintain a sponsor policy: no paid influence over article ranking or episode claims.
376 +- Add host-read sponsor spots only after listener traction, privacy review, and disclosure templates exist.
377 +- Sponsorship copy must be reviewed and clearly labeled in the audio and show notes.
378 +- Website sponsorship/support placements must be clearly labeled and must not weaken the no-paid-placement editorial promise.
379 +- Website ads require cookie/consent and privacy review before activation.
380
308 -### Phase 3: Premium and events
381 +### Phase 3: Advanced monetization
382
310 -- Premium feed, sponsored deep dives, or live events can be explored after the core feed has reliable cadence and listener metrics.
383 +- Dynamic ad insertion, premium feeds, sponsored deep dives, or live events can be explored after the core podcast cadence is reliable and listener metrics justify complexity.
384 - Premium feeds require authentication/payment provider design and privacy review.
385 +- Dynamic ads require privacy, consent, retention, vendor, and disclosure review before implementation.
386
387 ---
388
@@ -317,26 +391,34 @@ SquadScope should not store payment data. Use Stripe, PayPal, Ko-fi, Patreon, or
391 ### In scope
392
393 - One episode per weekly article.
394 +- Separate podcast product targeting Spotify or a podcast platform.
395 - Two-host script generated from article plus existing evidence artifacts.
396 - Claim ledger and source-backed show notes.
397 - Human review before synthesis.
398 - TTS provider selected after a Phase 2 listening-test POC.
324 -- MP3 post-processing and Blob Storage hosting.
325 -- Podcast RSS feed and weekly article embed.
399 +- MP3 post-processing and temporary Azure Blob Storage staging with retention/cleanup.
400 +- Manual Spotify/platform publishing packet.
401 +- Spotify/API and podcast-provider automation research.
402 +- Website configurable external podcast link only.
403 - AI voice disclosure and correction path.
327 -- Cost ledger and monthly budget guardrail covering TTS, storage, egress, script generation, validation, and CDN if used.
328 -- Manual dispatch and post-publish workflow trigger.
404 +- Cost ledger and monthly budget guardrail covering TTS, staging storage, script generation, validation, and platform/provider costs.
405 +- Manual invocation and safe post-publish artifact/event handoff.
406 +- Repository/project boundary defined before infrastructure code is written.
407
408 ### Out of scope for MVP
409
410 +- Hosting the podcast in the SquadScope website.
411 +- Website-hosted podcast RSS for listener consumption.
412 +- Article audio embeds, embedded players, Hugo podcast shortcodes, and website-hosted player pages are non-MVP/deferred.
413 +- Automated Spotify publishing before API feasibility is verified.
414 - Dynamic ad insertion.
415 - Premium/private feeds.
416 - Real-time/daily episodes.
417 - Multiple languages.
336 -- Listener analytics beyond basic hosting logs, unless privacy/consent work is done.
418 +- Listener analytics beyond platform basics, unless privacy/consent work is done.
419 - Fully automated publish without human review.
420 - Voice cloning or real-person mimicry.
339 -- CDN optimization, unless needed for stable public enclosure URLs.
421 +- CDN optimization for audio delivery.
422
423 ---
424
@@ -344,56 +426,63 @@ SquadScope should not store payment data. Use Stripe, PayPal, Ko-fi, Patreon, or
426
427 ### Product acceptance
428
347 -- A reviewer can inspect the reviewed script artifact, claim ledger, show notes, transcript, manifest, and generated audio, then map every substantive factual claim to the published article and cited source/artifact validation.
429 +- A reviewer can inspect the reviewed script artifact, claim ledger, show notes, transcript, publishing packet, manifest, and generated audio, then map every substantive factual claim to the published article and cited source/artifact validation.
430 - Episode length fits the 8-12 minute show format, and automated MVP runs are no more than 10 minutes unless manually overridden.
431 - The show sounds distinct from copied podcasts and uses the approved `Signal Check` structure.
432 - Jokes clarify or compress analysis without adding unsupported claims or targeting individuals unfairly.
351 -- AI voice disclosure is audible in the first 60 seconds and visible in show notes.
352 -- Corrections path is present in show notes and article embed.
433 +- AI voice disclosure is audible in the first 60 seconds and visible in show notes/platform description.
434 +- Corrections path and source article URL are present in the manual publishing packet.
435 +- Website integration, if present, is only an external configurable podcast link.
436
437 ### Technical acceptance
438
356 -- Podcast workflow can be rerun for a selected week without duplicate episodes.
357 -- Article publishing succeeds even if podcast generation fails.
358 -- MP3 is hosted outside git, under the size/duration/audio constraints.
359 -- 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).
360 -- Cost ledger records provider, character count, duration, TTS/storage/egress/script-generation/validation/CDN estimated or actual costs, and monthly budget status.
439 +- Podcaster workflow can be rerun for a selected week without duplicate episodes.
440 +- Article publishing behavior, publish manifests, deploy timing, and success criteria are unchanged even if podcast generation fails or never runs.
441 +- MP3 is staged outside git, under the size/duration/audio constraints.
442 +- Temporary Blob artifacts have documented access controls, retention, and cleanup.
443 +- Manual publishing packet includes MP3, title, description, transcript/show notes, disclosures, source article URL, and corrections link.
444 +- Spotify/API research documents whether direct upload/publish automation exists and what fallback path is recommended.
445 +- Cost ledger records provider, character count, duration, TTS/staging/script-generation/validation/platform estimated or actual costs, and monthly budget status.
446 - Secrets are not logged or committed.
447
448 ### Safety acceptance
449
365 -- Human reviewer approval is recorded via GitHub Environment `podcast-review` before synthesis; reviewers inspect `script.md`, `claim_ledger.json`, `show_notes.md`, `transcript.md`, and `episode_manifest.json` before allowing TTS.
450 +- Human reviewer approval is recorded via the Podcaster review gate before synthesis; a temporary in-repo prototype may use GitHub Environment `podcast-review`. Reviewers inspect `script.md`, `claim_ledger.json`, `show_notes.md`, `transcript.md`, `publishing_packet.md`, and `episode_manifest.json` before allowing TTS.
451 - Provider voice license and AI disclosure are documented.
452 - No real-person voice cloning or protected podcast imitation occurs.
368 -- Sponsorship/affiliate text, if present, is disclosed before the relevant segment.
453 +- Sponsorship/affiliate/support text, if present, is disclosed before the relevant segment.
454 - Privacy policy changes are merged before any non-dry-run TTS call and before production analytics/providers beyond current hosting are enabled.
455
456 ---
457
458 ## Implementation Phases
459
375 -1. **Design and contracts:** Define manifest, claim ledger, show notes, RSS fields, storage naming, and review statuses.
376 -2. **Script generation dry run:** Generate script/ledger/show notes from existing weekly articles without TTS or publishing.
377 -3. **TTS proof of concept:** After the privacy update, synthesize reviewed private samples with Azure Speech Standard, Azure Speech HD/OpenAI voices in Azure if available, and OpenAI `tts-1` or `gpt-4o-mini-tts`; run a listening test and select the provider before full storage/RSS infrastructure.
378 -4. **Audio hosting and RSS:** Upload approved MP3s to Blob Storage, generate `/podcast/index.xml`, and validate enclosures.
379 -5. **Article embed:** Add a Hugo `podcast-episode` shortcode/partial so weekly articles can render audio player, transcript link, show notes, and AI disclosure while keeping `unsafe = false` unchanged.
380 -6. **MVP launch:** Enable non-blocking post-publish podcast workflow with human review gate.
381 -7. **Quality experiments:** Revisit voices, providers, music/SFX, and production polish after the Phase 2 provider decision and MVP reliability are proven.
382 -8. **Monetization experiments:** Add support/donation links first; defer ads/premium until disclosure, privacy, and audience metrics justify them.
460 +1. **Design and contracts:** Define the SquadScope export contract, Podcaster-owned manifest, claim ledger, show notes, publishing packet, staging storage, retention, review statuses, and website external-link configuration.
461 +2. **Repository/project boundary gate:** Decide the Podcaster repo/project boundary and Azure resource ownership before infrastructure code, secrets, or deploy workflows are written.
462 +3. **Script generation dry run:** Generate script/ledger/show notes/transcript/publishing packet from existing weekly articles without TTS or publishing, using only exported artifacts or manual input.
463 +4. **TTS proof of concept:** After the privacy update, synthesize reviewed private samples with Azure Speech Standard, Azure Speech HD/OpenAI voices in Azure if available, and OpenAI `tts-1` or `gpt-4o-mini-tts`; run a listening test and select the provider.
464 +5. **Temporary staging:** Upload approved MP3s and packet artifacts to Podcaster-owned Azure Blob Storage with access controls, manifest recording, retention, and cleanup.
465 +6. **Spotify/API research:** Verify direct Spotify upload/publish support; if unsupported, document manual Spotify for Creators flow and/or podcast host/provider RSS/API options.
466 +7. **Manual launch:** Generate the publishing packet and manually publish to Spotify or selected platform.
467 +8. **Website external link:** Add a configurable link to the external podcast/platform page once available.
468 +9. **Quality experiments:** Revisit voices, providers, music/SFX, and production polish after the Phase 2 provider decision and MVP reliability are proven.
469 +10. **Monetization experiments:** Add support/donation links first; defer sponsorships, ads, premium feeds, and dynamic insertion until disclosure, privacy, and audience metrics justify them.
470
471 ---
472
473 ## Open Questions
474
388 -- Which Azure region and Speech resource should be used for production?
475 +- Which repository/project owns Podcaster implementation before Azure infrastructure is written?
476 +- Which Azure resource group/subscription, region, Speech resource, Blob account, identities, and budget alerts should Podcaster own for production?
477 - Which provider/voice pair wins the Phase 2 listening test while avoiding real-person mimicry?
478 - Which required reviewers should be configured on the GitHub Environment `podcast-review`?
391 -- Should RSS stay as standalone `static/podcast/index.xml`, or should a future Hugo `content/podcast/` section replace static XML generation?
479 +- Does Spotify currently support episode upload/publish automation, or is manual Spotify for Creators / provider RSS the right MVP path?
480 +- Which external podcast/platform page should the website link to after launch?
481 - What public podcast cover art should be used, and does it require a new design asset?
393 -- What is the minimum listener metric needed before monetization moves beyond donations?
482 +- What is the minimum listener metric needed before monetization moves beyond donations/support?
483
484 ---
485
486 ## Decision
487
399 -Proceed with this amended docs-only design. For implementation, build **SquadScope: Signal Check** as a human-reviewed, source-backed, two-host weekly podcast using the GitHub Environment `podcast-review` gate, explicit post-publish dispatch from `crawl-and-publish.yml`, a Phase 2 TTS listening-test provider decision, stable public Blob/CDN enclosure URLs, a Hugo `podcast-episode` shortcode/partial, and strict disclosure/privacy/safety/cost gates. Defer analytics, ads, premium feeds, music/SFX, and full automation until the MVP proves reliable and trustworthy.
488 +Proceed with this amended docs-only design. For implementation, build **SquadScope: Signal Check** through **Podcaster**, a human-reviewed, source-backed, two-host sister product/tool that consumes SquadScope's published article artifacts asynchronously and is distributed as a separate podcast product. Keep SquadScope's existing publishing behavior, gates, manifests, deploys, and critical path unchanged. Define the repository/project boundary and Azure resource ownership before infrastructure code is written; keep only docs/contracts and harmless prototypes in SquadScope until Podcaster is separated. Use a review gate, post-publish artifact/API/URL handoff or manual invocation, a Phase 2 TTS listening-test provider decision, Podcaster-owned temporary Azure Blob Storage staging with retention/cleanup, a manual Spotify/platform publishing packet, Spotify/API automation research, a website external-link-only integration, and strict disclosure/privacy/safety/cost gates. Defer site-hosted podcast consumption, embedded players, ads, premium feeds, music/SFX, and full publish automation until the MVP proves reliable and trustworthy.
docs/podcast-generation-plan.md
+222 -148
@@ -1,50 +1,58 @@
1 # Podcast Generation Execution Plan
2
3 -**Issue:** #297
4 -**Date:** 2026-06-07
5 -**Lead:** Leela
3 +**Issue:** #310
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. Select the TTS provider in Phase 2 after a listening-test POC comparing Azure Speech Standard, Azure Speech HD/OpenAI voices in Azure if available, and OpenAI `tts-1` or `gpt-4o-mini-tts`; use Azure Blob Storage or CDN-backed stable public URLs for MP3s/transcripts/manifests and a separate non-blocking `podcast-generate.yml` workflow. Require claim ledger, source-backed show notes, AI voice disclosure, GitHub Environment review, cost guardrails, and RSS validation before public publish.
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. Podcaster is a **sister product/tool**, not a SquadScope website feature, and the podcast is published to Spotify or another podcast platform. SquadScope's website MVP only exposes a configurable external link to the podcast/platform page once available.
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).
14 +Select the TTS provider in Phase 2 after a listening-test POC comparing Azure Speech Standard, Azure Speech HD/OpenAI voices in Azure if available, and OpenAI `tts-1` or `gpt-4o-mini-tts`. Use Podcaster-owned Azure Blob Storage as temporary/staging artifact storage for generated MP3s, transcripts, manifests, and publishing packets, with retention and cleanup. Initial Spotify publishing is manual through an operator packet. Research whether Spotify supports podcast episode upload/publish automation before designing any automated publishing path. Keep only docs/contracts and harmless prototypes in SquadScope until the repository/project boundary is defined.
15 +
16 +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), 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). Spotify/API work must verify current Spotify for Creators and podcast delivery documentation; initial docs research suggests Spotify Web API is for streaming-service interactions such as metadata/playlists/playback, not clearly for episode upload.
17
18 ---
19
20 ## Guiding Constraints
21
22 - Do not commit MP3s or generated audio binaries to git.
23 +- Do not host the podcast in the SquadScope website for MVP.
24 +- Website work is limited to a configurable external podcast/platform link.
25 +- Zero impact on existing publishing: no changes to weekly crawl/analyze/generate/deploy behavior, no article-publish gating, no publish-manifest changes, and no audio steps in the critical path.
26 - Podcast failures must not block weekly article publishing.
22 -- MVP generation must require GitHub Environment `podcast-review` approval before TTS.
27 +- MVP generation must require Podcaster-owned review approval before TTS; a temporary in-repo prototype may use GitHub Environment `podcast-review`.
28 - 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.
29 +- Disclose AI-generated voices in the first 60 seconds and in show notes/platform descriptions.
30 - 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 total podcast spend, and max 10 minutes/episode.
27 -- If new Hugo data paths are added, update `hugo.toml` module mounts explicitly.
28 -- Update privacy policy before any non-dry-run TTS provider call and before adding podcast analytics, payment providers, or non-essential tracking.
31 +- Keep MVP to max 5 episodes/month, max $5/month total podcast spend unless manually raised, and max 10 minutes/episode.
32 +- Azure Blob Storage is temporary staging with retention/cleanup, not final public hosting for MVP; Azure resources must be owned by Podcaster once implementation moves beyond prototype/docs.
33 +- If an RSS feed is generated during MVP, it is for podcast-platform ingestion or future host/provider migration, not site-hosted consumption.
34 +- Update privacy policy before any non-dry-run TTS provider call and before adding podcast analytics, payment providers, external players, or non-essential tracking.
35 +- Define the repository/project boundary and Azure resource ownership before infrastructure code is written.
36
37 ---
38
39 ## Target Architecture
40
41 ```text
35 -crawl-and-publish.yml confirms normal weekly publish
36 - -> explicitly dispatch podcast-generate.yml with publish inputs, or operator manual dispatch
37 - -> load content/weekly/YYYY/Www.md and source artifacts
42 +SquadScope normal weekly publish completes unchanged
43 + -> SquadScope emits stable post-publish article URL/content/artifact manifest, or operator provides it manually
44 + -> Podcaster consumes that artifact/API/URL asynchronously
45 -> reject dry-run/candidate-only/restore/no-AI fallback replacement modes
39 - -> compute article hash and idempotency key
40 - -> derive claims from published article and validate against available artifacts
41 - -> generate outline, script, show notes, transcript
42 - -> GitHub Environment podcast-review gate
43 - -> selected TTS provider synthesis
46 + -> Podcaster computes article hash and idempotency key
47 + -> Podcaster derives claims from published article and validates against exported artifacts
48 + -> Podcaster generates outline, script, show notes, transcript, publishing packet draft
49 + -> Podcaster-owned review gate approves script package
50 + -> selected TTS provider synthesis outside SquadScope critical path
51 -> ffmpeg normalize/transcode
45 - -> upload MP3/transcript/manifest to Azure Blob Storage
46 - -> generate/update /podcast/index.xml
47 - -> embed episode in weekly article or data-driven episode block
52 + -> upload MP3/transcript/manifest/packet to Podcaster-owned temporary Azure Blob staging
53 + -> operator downloads/reviews publishing packet
54 + -> operator manually publishes to Spotify or selected platform
55 + -> record external episode URL and optionally update website external podcast link
56 ```
57
58 Idempotency key:
@@ -55,245 +63,311 @@ week + article_hash + script_prompt_version + voice_config_hash
63
64 ---
65
66 +## Architecture Options and Recommendation
67 +
68 +| Option | Description | Pros | Cons | Recommendation |
69 +| --- | --- | --- | --- | --- |
70 +| Option A: temporary folder in this repo | Keep planning, contracts, sample artifacts, and possibly throwaway prototypes in SquadScope. | Fastest way to iterate on the article export contract. | Risk of accidental coupling to publishing; cannot own Azure resources or critical workflows. | Allow only for docs/prototypes that cannot affect publishing. |
71 +| Option B: separate repo/project from the start | Create a `Podcaster` repo/project for implementation, tests, secrets, workflows, and releases. | Clean lifecycle and ownership; protects SquadScope publishing. | Requires setup before implementation. | Recommended before real implementation grows. |
72 +| Option C: Azure-native project/resource group | Give Podcaster its own Azure resource group/subscription boundary, IaC, identities, budget alerts, and deployment lifecycle. | Best governance for Speech, Blob, costs, and secrets. | Requires infra design and ownership decisions. | Required before any Azure resource deployment. |
73 +
74 +**Selected path:** keep PRD, plan, and artifact/API contract documentation in SquadScope now. Move implementation to a separate **Podcaster** project/repo before Azure resource deployment. Use a temporary folder in this repo only for prototypes that are manually invoked, isolated from publish manifests, and unable to affect crawl/analyze/generate/deploy.
75 +
76 +---
77 +
78 ## Phase 0: Product and Contract Finalization
79
60 -**Goal:** Lock the product contract before implementation.
80 +**Goal:** Lock the separate-product contract and zero-impact boundary before implementation.
81
82 ### Issues
83
64 -1. **Define podcast artifact schemas**
65 - - Files: `episode_manifest.json`, `claim_ledger.json`, `show_notes.md`, `transcript.md`, reviewed `script.md`.
66 - - Include week, article URL, article hash, prompt version, voice config, provider, cost, duration, byte length, disclosure status, reviewer, and publish status.
67 - - Acceptance: sample schema fixtures exist and document required/optional fields.
84 +1. **Define SquadScope export contract and podcast artifact schemas**
85 + - SquadScope exports only stable post-publish data: week, article URL/path, article content or hash, source artifact references, run ID, publish mode, and optional artifact manifest.
86 + - Podcaster owns `episode_manifest.json`, `claim_ledger.json`, `show_notes.md`, `transcript.md`, reviewed `script.md`, and `publishing_packet.md`.
87 + - Include week, article URL, article hash, prompt version, voice config, provider, cost, duration, byte length, disclosure status, reviewer, temporary Blob staging path, retention expiry, external publish URL, and publish status.
88 + - Acceptance: sample schema fixtures exist, document required/optional fields, and do not require changes to existing SquadScope publish manifests.
89
69 -2. **Define editorial script prompt and style guide**
90 +2. **Define repository/project boundary and Azure ownership gate**
91 + - Decide whether implementation starts in a separate `Podcaster` repo/project or a temporary isolated folder for prototypes only.
92 + - Decide Azure resource group/subscription, identities, Blob/Speech ownership, budget alerts, and deployment lifecycle before IaC or secrets are written.
93 + - Acceptance: no infrastructure code, Azure deployment workflow, or production credential is added until this gate is resolved.
94 +
95 +3. **Define editorial script prompt and style guide**
96 - Use `SquadScope: Signal Check` format.
97 - Segment order: cold open, The Signal, The Noise Check, The Gap, Receipts Round, Week Ahead, Outro.
98 - Host A Curator, Host B Skeptic.
99 - Acceptance: prompt requires citations, bans unsupported facts, bans copied podcast expression, and includes joke safety rules.
100
75 -3. **Configure GitHub Environment `podcast-review`**
101 +4. **Configure review gate for temporary prototype / Podcaster**
102 - Use required reviewers as the MVP review mechanism.
77 - - Workflow uploads `script.md`, `claim_ledger.json`, `show_notes.md`, `transcript.md`, and `episode_manifest.json` for inspection, then pauses before non-dry-run TTS.
103 + - A temporary SquadScope prototype or the separated Podcaster workflow uploads `script.md`, `claim_ledger.json`, `show_notes.md`, `transcript.md`, `publishing_packet.md`, and `episode_manifest.json` for inspection, then pauses before non-dry-run TTS.
104 - Acceptance: TTS cannot proceed without environment approval, and approval identity/time is recorded in the manifest.
105
106 ---
107
82 -## Phase 1: Script Dry Run, No Audio
108 +## Phase 1: Script Dry Run and Publishing Packet, No Audio
109
84 -**Goal:** Prove articles can become safe, useful scripts before adding TTS.
110 +**Goal:** Prove articles can become safe, useful scripts and operator-ready publishing packets before adding TTS.
111
112 ### Issues
113
88 -4. **Implement claim/source extraction**
89 - - Input: published weekly article plus available source artifacts.
114 +5. **Implement claim/source extraction**
115 + - Input: published weekly article plus SquadScope's exported URL/content/artifact manifest.
116 - Output: claim ledger derived from the published article, then validated against existing analysis/publish artifacts where available, with support status and source URLs.
117 - Acceptance: unsupported claims fail the gate or are marked for removal.
118
93 -5. **Generate episode outline and script**
119 +6. **Generate episode outline and script**
120 - Output 1,200-1,700 word two-host script.
121 - Include AI voice disclosure in first 60 seconds.
122 - Keep jokes aimed at hype cycles, not individuals.
123 - Acceptance: script passes length, segment, disclosure, and banned-phrase checks.
124
99 -6. **Generate show notes and transcript**
100 - - Show notes include article link, source links, AI disclosure, corrections link, and sponsorship disclosure placeholder.
125 +7. **Generate show notes, transcript, and manual publishing packet**
126 + - Show notes include article link, source links, AI disclosure, corrections link, and sponsorship/support disclosure placeholder.
127 - Transcript is derived from final script.
102 - - Acceptance: every source URL in the ledger appears in show notes or is intentionally excluded with reason.
128 + - Publishing packet includes MP3 placeholder/path, title, description, transcript/show notes, disclosures, source article URL, corrections link, reviewer info, and post-publish fields.
129 + - Acceptance: every source URL in the ledger appears in show notes or is intentionally excluded with reason; packet is sufficient for manual Spotify/platform publishing once audio exists.
130
104 -7. **Add dry-run validation command**
105 - - Validate ASCII filenames, required fields, claim support, disclosure, script length, and no fake sponsor language.
106 - - Acceptance: command exits non-zero on missing ledger/support/disclosure.
131 +8. **Add dry-run validation command**
132 + - Validate ASCII filenames, required fields, claim support, disclosure, script length, packet completeness, and no fake sponsor language.
133 + - Acceptance: command exits non-zero on missing ledger/support/disclosure/packet fields.
134
135 ---
136
137 ## Phase 2: TTS Proof of Concept
138
112 -**Goal:** Select the TTS provider using private samples before full storage/RSS infrastructure.
139 +**Goal:** Select the TTS provider using private reviewed samples before staging/publishing implementation.
140
141 ### Issues
142
116 -8. **Update privacy policy for TTS candidates before synthesis**
143 +9. **Update privacy policy for TTS candidates before synthesis**
144 - Document candidate voice providers, data sent, retention/region if configurable, and operator-facing disclosure before any non-dry-run TTS call.
145 - Acceptance: privacy PR is merged before provider credentials are used for non-dry-run synthesis.
146
120 -9. **Run TTS provider listening-test POC**
147 +10. **Run TTS provider listening-test POC**
148 - Compare Azure Speech Standard neural voices, Azure Speech HD/OpenAI voices in Azure if available, and OpenAI `tts-1` or `gpt-4o-mini-tts`.
149 - Use the same reviewed sample script, record billable characters, latency, licensing/privacy notes, voice naturalness, pronunciation, SSML/control support, and estimated total monthly cost.
123 - - Acceptance: provider decision is documented before storage/RSS implementation; private MP3 artifacts are generated only after `podcast-review` approval.
150 + - Acceptance: provider decision is documented before production staging/publish-packet implementation; private MP3 artifacts are generated only after review approval and outside SquadScope's publishing critical path.
151
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.
152 +11. **Post-process audio with ffmpeg**
153 + - Mono, 44.1 kHz, 64-96 kbps, `audio/mpeg`, target -16 LUFS, under 10 MB.
154 + - Acceptance: validation reports duration, loudness, sample rate, bitrate, channels, and byte length.
155
129 -11. **Add cost ledger and guardrails**
130 - - Track per-episode and monthly TTS, storage, egress/download bandwidth, script generation, validation, and CDN costs if used.
131 - - Enforce max 5 episodes/month, max $5/month total podcast spend, max 10 minutes; call out that egress may dominate if downloads grow.
132 - - Acceptance: workflow fails before non-dry-run synthesis or publish if limits would be exceeded.
156 +12. **Add cost ledger and guardrails**
157 + - Track per-episode and monthly TTS, temporary storage, script generation, validation, provider/platform costs, and any egress/download bandwidth if later introduced.
158 + - Enforce max 5 episodes/month, max $5/month total podcast spend unless manually raised, max 10 minutes; call out that hosting/provider/egress costs may dominate if downloads grow.
159 + - Acceptance: workflow fails before non-dry-run synthesis or publish-packet completion if limits would be exceeded.
160
161 ---
162
136 -## Phase 3: Storage and RSS
163 +## Phase 3: Temporary Staging and Manual Publish Readiness
164
138 -**Goal:** Publish standards-compliant podcast assets without bloating git.
165 +**Goal:** Produce validated audio and a complete manual publishing packet in Podcaster without making the website or SquadScope publishing flow the podcast host.
166
167 ### Issues
168
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 stable public anonymous read access, or CDN-backed stable public URLs. Expiring SAS URLs are prohibited for RSS enclosures.
146 - - Acceptance: uploaded MP3 is reachable over stable HTTPS without expiring query credentials.
169 +13. **Provision Podcaster-owned Azure Blob Storage staging conventions**
170 + - Example: `podcast-staging/YYYY/Www/squadscope-signal-check-YYYY-Www.mp3`.
171 + - ASCII filenames only.
172 + - Configure least-privilege workflow access, content type `audio/mpeg`, retention tags/metadata, and cleanup policy.
173 + - Acceptance: uploaded MP3 is available to authorized operators for manual publish and has a documented expiry/cleanup path.
174
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.
175 +14. **Implement staging retention and cleanup**
176 + - Delete or archive staging artifacts after successful platform publish, rejected review, or retention expiry.
177 + - Keep manifest metadata needed for audit without retaining unnecessary audio forever.
178 + - Acceptance: cleanup can run safely and records what was deleted or retained.
179
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.
180 +15. **Generate final manual Spotify/platform publishing packet**
181 + - Include final MP3, title, description, transcript/show notes, AI disclosure, sponsor/affiliate/support disclosures if any, source article URL, corrections link, reviewer identity/time, and post-publish fields.
182 + - Acceptance: an operator can publish using Spotify for Creators or the selected platform without reading workflow internals.
183
156 -15. **Generate static feed without future Hugo section conflict**
157 - - Start with standalone static XML under `static/podcast/index.xml` for isolated MVP.
158 - - Document that this must not conflict with a future Hugo `content/podcast/` section; if that section is added, remove or replace static XML generation so one feed owner remains.
159 - - Acceptance: no missing module mounts if data files are added, and build/feed validation proves only one `/podcast/index.xml` owner exists.
184 +16. **Record external publish result**
185 + - After manual publish, record external episode URL, platform/show URL, publish time, and any corrections/update notes in the manifest or issue comment.
186 + - Acceptance: website link work has a reliable external target when launch is approved, without modifying article publish manifests or critical path behavior.
187
188 ---
189
163 -## Phase 4: Site Integration
190 +## Phase 4: Spotify/API and Podcast Host Research
191
165 -**Goal:** Make episodes discoverable from the article and site.
192 +**Goal:** Determine whether publishing can be automated after the manual MVP.
193
194 ### Issues
195
169 -16. **Add Hugo `podcast-episode` shortcode/partial**
170 - - Add audio player or link block to matching weekly article after episode publish.
171 - - Include transcript, show notes, AI voice disclosure, and correction link.
172 - - Acceptance: weekly article renders through the shortcode/partial while `unsafe = false` remains unchanged.
196 +17. **Research Spotify upload/publish API support**
197 + - Verify current Spotify for Creators, Spotify podcast delivery, and Spotify Web API docs.
198 + - Caveat to test: initial docs research suggests Spotify Web API is for streaming-service interactions like metadata, playlists, playback, and library operations, not clearly podcast episode upload.
199 + - Acceptance: documented yes/no answer with links, auth model, required accounts, limitations, and operational risk.
200
174 -17. **Add podcast landing page**
175 - - Explain show format, disclosure, feed link, correction path, and methodology.
176 - - Acceptance: page builds in Hugo and links to `/podcast/index.xml`.
201 +18. **Research fallback automation paths**
202 + - If Spotify direct upload/publish is unavailable, evaluate podcast host/provider RSS APIs, provider-hosted distribution to Spotify, or a documented manual Spotify for Creators flow.
203 + - Include privacy, retention, analytics, cost, corrections/rollback, and disclosure implications.
204 + - Acceptance: recommendation chooses manual continuation, provider API, or future direct API with rationale.
205
178 -18. **Update methodology and privacy pages**
179 - - Methodology: explain article-to-podcast transformation and safety gates.
180 - - Privacy: document selected voice provider before non-dry-run TTS, Blob hosting logs, analytics/payment providers if used.
181 - - Acceptance: public docs match actual providers and data flows before launch.
206 +19. **Decide whether any RSS is needed for MVP operations**
207 + - If RSS is needed, scope it as platform/provider ingestion or future host migration only.
208 + - Do not publish a SquadScope-site-owned feed for listener consumption as MVP.
209 + - Acceptance: RSS decision explicitly states owner, consumer, URL strategy, and why it does not turn the website into the podcast host.
210
211 ---
212
185 -## Phase 5: Launch Controls
213 +## Phase 5: Website External Link Only
214
187 -**Goal:** Enable reliable weekly operation.
215 +**Goal:** Make the external podcast discoverable with a simple website link only, without hosting it on SquadScope or changing article publishing.
216
217 ### Issues
218
191 -19. **Create `podcast-generate.yml` with safe triggering**
192 - - Preferred automated trigger: `crawl-and-publish.yml` explicitly dispatches `podcast-generate.yml` only after confirmed normal publish, passing week, article path/URL, source run ID, publish mode, and artifact identifiers.
193 - - Include manual `workflow_dispatch` for selected week. Do not naively use `workflow_run`; if used later, fetch and verify triggering run inputs/artifacts before synthesis.
194 - - Dry-run, candidate-only, restore, failed, or no-AI fallback replacement runs must not synthesize audio.
195 - - Must be non-blocking relative to `crawl-and-publish.yml`.
196 - - Acceptance: failed podcast run does not fail or roll back article publishing, and unsafe publish modes are rejected before TTS.
219 +20. **Add configurable external podcast link**
220 + - Link target can be Spotify show page or selected platform page.
221 + - Link must be easy to disable until launch.
222 + - Include concise AI/generated podcast disclosure if needed near the link or in methodology/privacy updates.
223 + - Acceptance: site builds with link enabled/disabled and does not add an audio player, article embed, website-hosted player page, or site-owned listener feed; those website-hosted consumption patterns remain non-MVP/deferred.
224
198 -20. **Add GitHub Environment `podcast-review` gate**
199 - - Require environment approval after script generation and before TTS.
200 - - Reviewers inspect `script.md`, `claim_ledger.json`, `show_notes.md`, `transcript.md`, and `episode_manifest.json`.
201 - - Acceptance: unapproved scripts stop before synthesis.
225 +21. **Update methodology and privacy pages**
226 + - Methodology: explain article-to-podcast transformation, safety gates, manual/platform publishing, and correction path.
227 + - Privacy: document selected voice provider, temporary Blob staging logs/retention, platform/provider links, analytics/payment providers if used.
228 + - Acceptance: public docs match actual providers and data flows before launch.
229
203 -21. **Add observability**
204 - - Log episode key, provider, duration, cost estimate, byte length, validation results, and publish URL.
205 - - Do not log secrets or full provider credentials.
206 - - Acceptance: operator can diagnose failures from workflow summary.
230 +---
231
208 -22. **Pilot launch with one back-catalog episode**
209 - - Generate one recent weekly episode as a pilot.
210 - - Do not submit to directories until RSS and safety checks pass.
211 - - Acceptance: reviewer signs off on audio quality, citations, disclosure, and feed validity.
232 +## Phase 6: Launch Controls
233 +
234 +**Goal:** Enable reliable weekly operation with manual platform publishing while leaving SquadScope publishing unaffected.
235 +
236 +### Issues
237 +
238 +22. **Create post-publish handoff or Podcaster workflow**
239 + - In SquadScope, any future workflow should only emit a post-publish event/artifact after confirmed normal publish, or be manually invoked for prototypes.
240 + - The podcast generation workflow should live in Podcaster once separated and consume week, article path/URL, source run ID, publish mode, and artifact identifiers asynchronously.
241 + - Do not naively use `workflow_run`; if used later, fetch and verify triggering run inputs/artifacts before synthesis.
242 + - Dry-run, candidate-only, restore, failed, or no-AI fallback replacement runs must not synthesize audio.
243 + - Must be non-blocking relative to `crawl-and-publish.yml` and must not change existing publish manifests.
244 + - Acceptance: failed podcast run does not fail or roll back article publishing, and unsafe publish modes are rejected before TTS.
245 +
246 +23. **Add Podcaster review gate**
247 + - Require approval after script generation and before TTS; a temporary in-repo prototype may use GitHub Environment `podcast-review`, while separated Podcaster owns its equivalent gate.
248 + - Reviewers inspect `script.md`, `claim_ledger.json`, `show_notes.md`, `transcript.md`, `publishing_packet.md`, and `episode_manifest.json`.
249 + - Acceptance: unapproved scripts stop before synthesis.
250 +
251 +24. **Add observability**
252 + - Log episode key, provider, duration, cost estimate, byte length, staging path, retention expiry, validation results, and external publish URL when known.
253 + - Do not log secrets or full provider credentials.
254 + - Acceptance: operator can diagnose failures from workflow summary.
255 +
256 +25. **Pilot launch with one back-catalog episode**
257 + - Generate one recent weekly episode as a pilot.
258 + - Publish manually to Spotify or selected platform after safety checks pass.
259 + - Acceptance: reviewer signs off on audio quality, citations, disclosure, publishing packet, staging cleanup, and external episode URL.
260
261 ---
262
215 -## Phase 6: Quality and Monetization Experiments
263 +## Phase 7: Quality and Monetization Experiments
264
265 **Goal:** Improve quality and revenue only after trust and reliability.
266
267 ### Issues
268
221 -23. **Add licensed music/SFX later, if desired**
222 - - MVP is voice-only. Select a licensed track/effect only in a later issue, and record license details in the episode manifest.
223 - - Acceptance: no music/SFX ships until license, attribution/disclosure, loop/edit rules, and reviewer approval criteria are documented.
269 +26. **Add licensed music/SFX later, if desired**
270 + - MVP is voice-only. Select a licensed track/effect only in a later issue, and record license details in the episode manifest.
271 + - Acceptance: no music/SFX ships until license, attribution/disclosure, loop/edit rules, and reviewer approval criteria are documented.
272
225 -24. **Add support/donation links**
226 - - Ko-fi/Patreon/PayPal/Stripe redirects only; do not store payment data.
227 - - Acceptance: privacy page and disclosure copy are updated.
273 +27. **Add support/donation links**
274 + - GitHub Sponsors/Ko-fi/Patreon/PayPal/Stripe redirects only; do not store payment data.
275 + - Website can link to support options once privacy and disclosure copy are updated.
276 + - Acceptance: privacy page, website copy, and show notes make clear support does not influence coverage or rankings.
277
229 -25. **Define sponsorship policy**
230 - - FTC requires material connections to be disclosed clearly and conspicuously (https://www.ftc.gov/business-guidance/resources/ftcs-endorsement-guides-what-people-are-asking).
231 - - Acceptance: sponsor copy template discloses before sponsor segment and forbids sponsor influence over rankings.
278 +28. **Define sponsorship policy**
279 + - FTC requires material connections to be disclosed clearly and conspicuously (https://www.ftc.gov/business-guidance/resources/ftcs-endorsement-guides-what-people-are-asking).
280 + - Acceptance: sponsor copy template discloses before sponsor segment and forbids sponsor influence over rankings.
281 +
282 +29. **Evaluate premium feed or dynamic ads**
283 + - Defer until audience metrics justify complexity.
284 + - Acceptance: privacy, consent, payment, provider, RSS/auth if applicable, and disclosure designs are approved before implementation.
285 +
286 +---
287
233 -26. **Evaluate premium feed or dynamic ads**
234 - - Defer until audience metrics justify complexity.
235 - - Acceptance: privacy, consent, payment, RSS auth, and disclosure designs are approved before implementation.
288 +## Existing Issue Mapping
289 +
290 +| Issue | Status | Role in corrected scope |
291 +| --- | --- | --- |
292 +| #301 Podcast: decide and enforce script human-review gate | Open | Keep; maps to `podcast-review` gate. |
293 +| #302 Podcast: implement safe trigger handoff from weekly publish | Open | Amend; SquadScope may emit only a post-publish artifact/event, while generation belongs in Podcaster once separated. |
294 +| #303 Podcast: add Hugo-safe episode embed shortcode | Closed | Closed as superseded by platform-podcast scope; no MVP embed. |
295 +| #304 Podcast: update privacy policy before TTS provider use | Open | Keep; privacy-before-TTS and future platform/provider/payment disclosures. |
296 +| #305 Podcast: decide Blob Storage public enclosure strategy | Open | Amend to staging/retention strategy; public enclosure is not MVP unless platform/provider path requires it. |
297 +| #306 Podcast: run early TTS quality bakeoff | Open | Keep; Phase 2 provider listening-test POC. |
298 +| #307 Podcast: add website link to external podcast only | Open | Keep; replaces site embed/player work. |
299 +| #308 Podcast: research Spotify publishing API and automation path | Open | Keep; required before automated publishing. |
300 +| #309 Podcast: generate weekly publishing packet after article publish | Open | Keep; manual Spotify/platform publishing packet. |
301 +| #310 Correct podcast PRD scope: platform podcast, website link only | Open | This docs-only correction. |
302
303 ---
304
305 ## Implementation Issue Creation Gate
306
241 -Before implementation begins, create or update GitHub issues for every P0/P1 row below. This correction pass only amends the docs; it does not need to create the implementation issues. The P0/P1 set must include the rubber-duck P0s: `podcast-review` environment approval, safe explicit dispatch/trigger gating, privacy-before-TTS sequencing, Phase 2 provider comparison, stable enclosure URL strategy, Hugo shortcode/partial embed, static RSS/Hugo section conflict guard, voice-only MVP/music licensing deferral, claim-ledger derivation/validation, and total podcast cost guardrails.
307 +Before implementation begins, create or update GitHub issues for every P0/P1 row below. This correction pass only amends docs; it does not need to create implementation issues. The P0/P1 set must include: repository/project boundary and Azure resource ownership before infrastructure code, Podcaster-owned review approval, safe post-publish artifact/event handoff, privacy-before-TTS sequencing, Phase 2 provider comparison, temporary Blob staging with retention/cleanup, manual publishing packet, Spotify/API research, website external-link-only integration, voice-only MVP/music licensing deferral, claim-ledger derivation/validation, and total podcast cost guardrails.
308
309 ## Suggested Issue Breakdown
310
245 -| Priority | Issue title | Owner | Depends on |
246 -| --- | --- | --- | --- |
247 -| P0 | Define podcast artifact schemas and idempotency key | Leela/Bender | PRD approval |
248 -| P0 | Define Signal Check editorial prompt and safety style guide | Farnsworth/Hermes | PRD approval |
249 -| P0 | Implement claim ledger extraction and validation | Farnsworth/Fry | schemas |
250 -| P0 | Generate dry-run scripts/show notes/transcripts | Farnsworth | prompt, ledger |
251 -| P0 | Configure GitHub Environment `podcast-review` gate | Hermes/Leela | dry run |
252 -| P1 | Update privacy policy for TTS provider candidates | Hermes/Leela | prompt, ledger |
253 -| P1 | Run TTS provider listening-test POC and select provider | Bender/Farnsworth | privacy update, review gate |
254 -| P1 | Add safe explicit podcast workflow dispatch gating | Hermes/Bender | dry run |
255 -| P1 | Add ffmpeg audio validation and normalization | Bender/Fry | TTS POC |
256 -| P1 | Add total podcast cost ledger and monthly guardrails | Hermes/Bender | TTS POC |
257 -| P1 | Upload podcast assets with stable public Blob/CDN URLs | Bender | audio validation |
258 -| P1 | Generate static podcast RSS without Hugo section conflict | Bender/Fry | storage |
259 -| P1 | Add Hugo podcast-episode shortcode/partial embed | Bender | RSS/storage |
260 -| P1 | Update methodology and privacy pages for podcast launch | Hermes/Leela | provider choices |
261 -| P2 | Pilot one back-catalog episode | Leela/Farnsworth | P1 complete |
262 -| P2 | Add licensed music/SFX only after manifest license design | Farnsworth/Hermes | MVP pilot |
263 -| P2 | Add support/donation links | Hermes | privacy update |
264 -| P3 | Evaluate ads, premium feed, or live events | Hermes/Leela | audience metrics |
311 +| Priority | Issue | Issue title | Owner | Depends on |
312 +| --- | --- | --- | --- | --- |
313 +| P0 | #310 | Correct PRD/plan to platform podcast scope | Leela | User clarification |
314 +| P0 | New/update | Define Podcaster repository/project boundary and Azure resource ownership | Leela/Bender | PRD approval |
315 +| P0 | #301 | Decide and enforce Podcaster script human-review gate | Leela/Hermes | boundary gate |
316 +| P0 | New/update | Define SquadScope export contract, podcast artifact schemas, idempotency key, and publishing packet contract | Leela/Bender | boundary gate |
317 +| P0 | New/update | Define Signal Check editorial prompt and safety style guide | Farnsworth/Hermes | PRD approval |
318 +| P0 | New/update | Implement claim ledger extraction and validation | Farnsworth/Fry | schemas |
319 +| P0 | #309 | Generate dry-run scripts/show notes/transcripts and manual publishing packet | Farnsworth | prompt, ledger |
320 +| P1 | #304 | Update privacy policy for TTS provider candidates | Hermes/Leela | prompt, ledger |
321 +| P1 | #306 | Run TTS provider listening-test POC and select provider | Bender/Farnsworth | privacy update, review gate |
322 +| P1 | #302 | Add safe post-publish artifact/event handoff or manual invocation | Hermes/Bender | export contract |
323 +| P1 | New/update | Add ffmpeg audio validation and normalization | Bender/Fry | TTS POC |
324 +| P1 | New/update | Add total podcast cost ledger and monthly guardrails | Hermes/Bender | TTS POC |
325 +| P1 | #305 | Upload podcast assets to Podcaster-owned temporary Blob staging with retention/cleanup | Bender | boundary gate, audio validation |
326 +| P1 | #308 | Research Spotify publish API and fallback provider/RSS/manual paths | Leela/Bender | PRD approval |
327 +| P1 | #307 | Add configurable website link to external podcast/platform page | Bender | external show URL |
328 +| P1 | New/update | Update methodology and privacy pages for podcast launch | Hermes/Leela | provider/platform choices |
329 +| P2 | New/update | Pilot one back-catalog episode with manual Spotify/platform publish | Leela/Farnsworth | P1 complete |
330 +| P2 | New/update | Add licensed music/SFX only after manifest license design | Farnsworth/Hermes | MVP pilot |
331 +| P2 | New/update | Add support/donation links | Hermes | privacy update |
332 +| P3 | New/update | Evaluate sponsorships, dynamic ads, premium feeds, or live events | Hermes/Leela | audience metrics |
333
334 ---
335
336 ## Phase Acceptance Criteria
337
270 -- Phase 0 is complete when schemas, prompts, and review status are documented well enough for implementation without product ambiguity.
271 -- Phase 1 is complete when a weekly article can produce a reviewed script, transcript, show notes, and claim ledger without audio synthesis.
338 +- Phase 0 is complete when the SquadScope export contract, Podcaster boundary, Azure ownership, schemas, prompts, review status, staging rules, and publishing packet contract are documented well enough for implementation without product ambiguity.
339 +- Phase 1 is complete when a weekly article can produce a reviewed script, transcript, show notes, claim ledger, and manual publishing packet without audio synthesis.
340 - Phase 2 is complete when privacy docs are updated, reviewed sample scripts are synthesized privately across candidate providers, a listening-test decision selects the MVP provider, and output fits duration, size, loudness, and total cost limits.
273 -- Phase 3 is complete when storage and RSS validation prove public episode delivery meets podcast-client requirements.
274 -- Phase 4 is complete when the article embed, landing page, methodology, and privacy updates accurately describe the launched experience.
275 -- Phase 5 is complete when the non-blocking workflow can publish a pilot episode and leave article publishing unaffected by podcast failures.
341 +- Phase 3 is complete when Podcaster-owned temporary Blob staging, retention, cleanup, and manual publish packet generation work for validated audio.
342 +- Phase 4 is complete when Spotify/API research determines whether direct upload/publish automation exists and recommends manual, provider API, or future direct API path.
343 +- Phase 5 is complete when the website can show or hide a configurable external podcast/platform link without hosting or embedding the podcast.
344 +- Phase 6 is complete when Podcaster can generate a reviewed episode package from a post-publish artifact/API/URL or manual invocation, support manual platform publishing, record the external URL, and leave article publishing unaffected by podcast failures.
345
346 ## Validation Checklist for First Public Episode
347
348 - [ ] 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.
280 -- [ ] AI voice disclosure is in first 60 seconds and show notes.
349 +- [ ] AI voice disclosure is in first 60 seconds and show notes/platform description.
350 - [ ] Claim ledger has no unsupported public claims.
282 -- [ ] GitHub Environment `podcast-review` approved script artifacts before synthesis.
351 +- [ ] Podcaster review gate (or temporary prototype `podcast-review` environment) approved script artifacts before synthesis.
352 - [ ] Provider voice license/privacy terms are documented before non-dry-run TTS.
353 - [ ] No real-person voice cloning or protected podcast imitation.
354 - [ ] No fake sponsor language.
355 - [ ] No music/SFX in MVP unless a later licensed-track manifest issue is complete.
356 - [ ] Show notes include source URLs and corrections link.
357 +- [ ] Publishing packet includes MP3, title, description, transcript/show notes, disclosures, source article URL, and corrections link.
358 - [ ] MP3 is mono, 44.1 kHz, 64-96 kbps, `audio/mpeg`, normalized near -16 LUFS, and under 10 MB.
289 -- [ ] Audio is hosted outside git.
290 -- [ ] RSS includes stable GUID, enclosure URL/length/type, RFC 2822 pubDate, and ASCII URLs.
291 -- [ ] Audio endpoint supports HEAD and byte-range requests.
292 -- [ ] Total cost ledger is updated for TTS, storage, egress, script generation, validation, CDN if used, and monthly guardrails pass.
293 -- [ ] Privacy and methodology pages match actual providers and analytics.
359 +- [ ] Audio is staged outside git in Podcaster-owned storage with retention and cleanup metadata.
360 +- [ ] Manual Spotify/platform publishing path is documented for the operator.
361 +- [ ] External episode URL is recorded after publish.
362 +- [ ] Website, if updated, links only to the external podcast/platform page and does not host podcast consumption.
363 +- [ ] Spotify/API automation remains unimplemented until research verifies support and a design is accepted.
364 +- [ ] Total cost ledger is updated for TTS, staging storage, script generation, validation, platform/provider costs, and monthly guardrails pass.
365 +- [ ] SquadScope weekly crawl/analyze/generate/deploy behavior, publish manifests, article gates, and deploy success criteria are unchanged.
366 +- [ ] Repository/project boundary and Azure resource ownership are approved before any infrastructure code or production secret is added.
367 +- [ ] Privacy and methodology pages match actual providers, storage, platform links, analytics, and support/payment options.
368
369 ---
370
371 ## Definition of Done for MVP
372
299 -The MVP is done when a confirmed normal weekly article publish explicitly dispatches a non-blocking podcast workflow that creates a reviewed, source-backed two-host episode; passes the GitHub Environment `podcast-review` gate; synthesizes it with the Phase 2-selected provider; uploads validated MP3/transcript/show notes/manifests to stable public Blob/CDN URLs; publishes a valid RSS item; embeds the episode through the Hugo `podcast-episode` shortcode/partial; records total cost; and leaves weekly article publishing unaffected if podcast generation fails.
373 +The MVP is done when Podcaster consumes a confirmed normal weekly article's post-publish artifact/API/URL or a manual operator input and creates a reviewed, source-backed two-host episode; passes the Podcaster review gate; synthesizes it with the Phase 2-selected provider; stages validated MP3/transcript/show notes/manifests/publishing packet in Podcaster-owned Azure Blob Storage with retention/cleanup; enables an operator to manually publish to Spotify or the selected podcast platform; records the external episode URL; optionally exposes only a configurable website link to that external podcast/page; records total cost; and leaves SquadScope weekly article publishing behavior, manifests, deploys, and success criteria unchanged whether podcast generation succeeds, fails, or never runs.