Repository navigation
Description
Product-owner deadline
ChannelForge must not become a multi-year architecture project.
Target: a fully usable living-room product by March 31, 2027.
This is a delivery constraint for #62 One Guide, Every Screen and the SER8 reference experience. Architecture, research, refactors, and provider integrations must be sequenced to produce usable vertical slices continuously rather than postponing value until every planned subsystem exists.
Primary product outcome
By the target date, a normal user should be able to:
- install/start ChannelForge on a supported host/reference setup;
- connect the services they already use through a simple Connect Your Services workflow;
- safely add IPTV/M3U/XMLTV/XC sources;
- see what each connected provider can actually expose;
- receive one normalized live-programming guide plus useful filtered views;
- browse Guide, Live Now, Starting Soon, Sports, Wrestling, and Search;
- see one canonical event when several providers carry the same event;
- press one remote button to launch the best supported authorized source;
- return reliably to the ChannelForge home surface;
- operate the SER8 reference client with the Harmony Elite without routine keyboard/mouse use;
- survive restart, provider failure, refresh failure, and credential expiry without losing last-known-good state;
- understand in plain language when a provider cannot expose a capability ChannelForge would like to use.
Initial service targets
The six-month product must design for and attempt supported integration with the user's core service classes:
- DIRECTV Stream
- Disney+
- ESPN / ESPN+ / ESPN Unlimited
- Netflix
- YouTube
- Plex / Plex Live TV
- IPTV / M3U / XMLTV / XC
A provider does not block the release merely because its current public/supported integration surface cannot expose every desired capability.
For each provider, ChannelForge must truthfully declare what is available:
- account connection/authentication
- live channel enumeration
- schedule/guide metadata
- scheduled/live event metadata
- entitlement/availability evidence
- search/discovery metadata
- launch/deep-link/browser target
- refresh behavior
- interactive reauthentication requirement
Unsupported capabilities remain explicit. Do not bypass DRM, authentication, access controls, provider terms, or regional restrictions to make a matrix look complete.
Delivery principle
Vertical slice before framework expansion.
Every major architectural abstraction must be proven by a real end-to-end user path as early as possible.
Do not build:
- a generalized framework with no working provider;
- a canonical model with no client using it;
- a credential vault with no connected service;
- a guide API with no remote-controlled guide;
- a launcher layer with no real provider launch.
Six-month sequencing
Phase 1 — Foundation closure and platform decision
Target: October 2026
- Close the current Alpha.1 source-set / multi-guide path (Alpha.1 — multi-source Guided Setup, web-link enrollment, guide bindings, and evidence-driven guide validation #175) or explicitly re-scope residual work.
- Define the minimum canonical content/event/availability model needed by Universal Live Guide — one normalized timeline across linear TV, live streaming, sports, and scheduled events #186.
- Define the provider capability contract in Streaming Provider Availability Adapters — normalize schedules, offerings, entitlements, and launch metadata #187.
- Define the secure account connection/secret boundary in Secure Provider Account Connections — credential vault, OAuth/session tokens, capability discovery, and reauthentication #189.
- Complete the SER8 platform evaluation in SER8 Living-Room Reference Client — appliance UX, Harmony control, and platform selection #188 using real provider/DRM/remote evidence.
- Choose the reference-client platform.
- Preserve current deterministic/LKG/immutable-generation guarantees.
Exit: one documented architecture that is small enough to implement immediately, with no unresolved platform question blocking development.
Phase 2 — First real cross-provider vertical slice
Target: November 2026
Deliver one working path from account/source connection through guide to launch:
- IPTV/M3U/XMLTV as the mature baseline;
- Plex/Plex Live TV as the first rich media-server provider;
- at least one real streaming provider capability adapter;
- ChannelForge canonical guide query;
- first 10-foot guide client on SER8;
- Harmony navigation for Home/Guide/Back/Select;
- one-action launch and reliable return to Home.
Exit: the system is demonstrably more than an IPTV formatter.
Phase 3 — Core provider expansion and event identity
Target: December 2026
- Add/validate provider capability adapters for the core service set as technically permitted.
- Integrate Event Intelligence Engine — automatic live-event discovery, schedule verification, and learned EPG generation #28/AED-compatible event pattern intelligence and automatic guide inference #121 event identity into the Universal Live Guide.
- Deduplicate equivalent sports/wrestling/live events across providers.
- Implement Live Now / Starting Soon / Sports / Wrestling views.
- Implement preferred source + alternate sources.
- Introduce Kodi-compatible M3U/XMLTV projection if the platform evaluation shows it adds value.
Exit: a user can browse a useful cross-provider live guide and launch content from the couch.
Phase 4 — Reliability, authentication lifecycle, and zero-touch refresh
Target: January 2027
- Account reauthentication/expiry handling.
- Scheduled provider/source refresh via Autonomous Operations — scheduled refresh, multi-guide learning, source drift detection, and zero-touch maintenance #35.
- LKG behavior for unavailable providers.
- Refresh/freshness/confidence indicators.
- Fast indexed queries for the 10-foot UI.
- Startup/wake/crash recovery on SER8.
- Provider-specific failures isolated from the rest of the product.
- Beginner-friendly setup and diagnostics.
Exit: daily household use does not require developer intervention.
Phase 5 — Product completion and usability
Target: February 2027
- Universal Search integration.
- Remote-complete text/search fallback.
- Guide filters/projections and favorites needed for daily use.
- Polish source-selection behavior.
- Simplify setup decisions.
- Performance profiling on the SER8.
- Full documentation and screenshots.
- Clean-install / upgrade / recovery testing.
Exit: feature-complete release candidate for the six-month target.
Phase 6 — Certification and usable release
Target: March 2027
- Real household soak testing.
- Exact-head quality/security gates.
- Provider capability matrix verified against current behavior.
- Remote-only living-room smoke suite.
- Upgrade/restart/failure recovery certification.
- Fix release-blocking UX/reliability defects only; defer nonessential expansion.
- Produce a reproducible downloadable release.
Exit: fully usable ChannelForge One Guide product by March 31, 2027.
Six-month release-driving issues
Required core:
- Autonomous Operations — scheduled refresh, multi-guide learning, source drift detection, and zero-touch maintenance #35 Autonomous Operations
- Epic: One Guide, Every Screen — unified television and streaming experience #62 One Guide, Every Screen
- Device & Deep Link Framework #67 Device & Deep Link Framework
- Best Source Recommendation Engine #70 Best Source Recommendation Engine
- Alpha.1 — multi-source Guided Setup, web-link enrollment, guide bindings, and evidence-driven guide validation #175 Alpha.1 multi-source / guide foundation
- Universal Live Guide — one normalized timeline across linear TV, live streaming, sports, and scheduled events #186 Universal Live Guide
- Streaming Provider Availability Adapters — normalize schedules, offerings, entitlements, and launch metadata #187 Streaming Provider Availability Adapters
- SER8 Living-Room Reference Client — appliance UX, Harmony control, and platform selection #188 SER8 Living-Room Reference Client
- Secure Provider Account Connections — credential vault, OAuth/session tokens, capability discovery, and reauthentication #189 Secure Provider Account Connections
Event/sports path:
- Event Intelligence Engine — automatic live-event discovery, schedule verification, and learned EPG generation #28 Event Intelligence Engine
- AED-compatible event pattern intelligence and automatic guide inference #121 AED-compatible event pattern intelligence
Output/client compatibility:
- Downstream Compatibility Profiles — target capability matrix and certified deterministic outputs #46 Downstream Compatibility Profiles
Other broader portfolio issues must not delay this product unless they are proven release blockers.
Scope discipline
The target is fully usable, not “every conceivable capability complete.”
For this release, defer work that does not materially improve:
- service connection;
- guide quality;
- content/event identity;
- source selection;
- playback launch;
- remote usability;
- reliability;
- security;
- beginner setup.
Examples of likely defer candidates unless directly needed:
- broad household-profile sophistication;
- generalized recommendation systems beyond source selection;
- extensive analytics/telemetry;
- exotic downstream targets;
- provider features unrelated to discovery/guide/launch;
- architectural generalization without immediate product use.
Required engineering behavior
- Ship small end-to-end increments.
- Maintain docs with every slice.
- Keep main releasable.
- Prefer proven provider-specific adapters behind a stable boundary over premature generic frameworks.
- Reuse existing ChannelForge deterministic, immutable, LKG, evidence, provenance, and review contracts.
- No rewrite of working foundations unless measured evidence requires it.
- No provider can silently become a new system of record.
- No security shortcut to hit the date.
Definition of "fully usable"
A release qualifies when it can be installed, configured, operated from the couch, refreshed, recovered, and upgraded by a normal user; the guide provides meaningful cross-provider value every day; supported content launches predictably; provider limitations are understandable; and routine use does not require source editing, shell commands, keyboard/mouse interaction, or developer intervention.
The six-month date is a scope-control mechanism, not permission to lower quality or security. When schedule pressure appears, reduce nonessential scope before reducing correctness, security, or recoverability.
Activity
Jumpstile commentedon Sep 27, 2026
Product-owner priority update: #191 is now release-driving. Guide quality is the primary product-quality metric. Provider breadth must not outrank correctness, completeness, freshness, classification, deduplication, or useful couch-first presentation.
If schedule pressure forces a tradeoff, ship fewer well-supported providers with an excellent guide rather than many weak integrations. Category-first discovery (Wrestling, Football, Baseball, Soccer, Movies, News, etc.) is part of the six-month usable-product definition.
Jumpstile commentedon Sep 27, 2026
Implementation-speed refinement: #192 is now release-driving. The six-month plan explicitly permits using mature off-the-shelf components (Kodi/PVR, Plex HTPC, browser runtimes, kiosk/shell facilities, remote middleware, etc.) when they materially accelerate delivery.
Acceptance bar: the user must perceive one coherent ChannelForge appliance. If a component exposes desktop switching, conflicting navigation, separate setup/maintenance burden, or manual recovery in normal use, it has not met the integration requirement.
Jumpstile commentedon Sep 27, 2026
Performance escalation: #193 is now release-driving. The March 2027 product is not acceptable if it is functionally correct but sluggish. Core couch actions must be served from local normalized/indexed state with measurable SER8 latency budgets; provider refresh/enrichment belongs off the foreground path.
Jumpstile commentedon Sep 27, 2026
Usability/visual-design escalation: #194 is now release-driving. The March 2027 product is not complete unless normal couch use is zero-instruction for a nontechnical first-time user, including older adults, and clean setup is radically simple. Visual beauty, accessibility, intuitive navigation, and low decision count are release criteria—not post-release polish.
Jumpstile commentedon Sep 27, 2026
Execution model update: #195 is now release-driving. The March 2027 target assumes autonomous, parallel, evidence-driven development—not serial manual work. Routine reversible implementation/research/test/docs decisions should proceed without product-owner interruption; escalate only genuine security, architecture, terms, or product-outcome decisions.
Jumpstile commentedon Sep 27, 2026
Cost/planning refinement: #195 now requires planning mode before nontrivial implementation and conservative model/token/tool routing. The March 2027 schedule should be achieved through reuse, narrow vertical slices, bounded parallelism, focused validation during iteration, and higher-cost reasoning only where difficulty/risk warrants it—not by maximizing agent/model usage.
Jumpstile commentedon Sep 27, 2026
DVR/timeshift scope update: #68 is now release-driving. The March 2027 product definition includes recording plus live pause/rewind. The plan should prove an actively maintained off-the-shelf backend first (Dispatcharr is the initial candidate), keep it behind a replaceable adapter/orchestration boundary, and defer native DVR mechanics until after the usable product unless the proof demonstrates that no existing backend can meet the seamless couch requirements.
Jumpstile commentedon Sep 27, 2026
TRUE_PLANNING_V1 — execution authority
Planning anchor: 2026-09-27.
This plan supersedes ad-hoc sequencing for the six-month living-room product. It does not supersede security, immutable acceptance, exact-head validation, or existing accepted ADRs unless explicitly amended.
1. Verified starting state
main:ccc8c0b21f49c37d0027af147c65c5e70db8f93c.75c47d3414e1a1a8c0f2a0fb916320da352a4a4a; hosted CI is green.2. Primary planning decision — NO REWRITE
Do not rebuild ChannelForge around the new vision.
Reuse the current engine as the authority for:
Add the new living-room product through bounded contracts:
3. Backend/client boundary
ChannelForge remains one backend authority with multiple projections/clients.
Kodi, Dispatcharr, Plex HTPC, browser runtimes, etc. may sit underneath but never become the canonical ChannelForge state authority.
4. Platform strategy — narrow proof, not broad bakeoff
Provisional first proof platform: Windows 11 on the SER8.
Reason:
This is not a permanent architectural lock-in.
Platform proof gate
Within the first platform spike prove on the actual SER8:
Only investigate Linux deeply if Windows fails a material requirement or creates unacceptable seams. This avoids an expensive OS bakeoff with low expected value.
5. DVR/timeshift strategy
#68 is now release-driving.
First proof candidate: Dispatcharr
Dispatcharr is the first reuse candidate because current evidence shows:
Critical proof requirement
Do not assume that in-progress-recording scrubbing equals universal live timeshift.
The proof must demonstrate:
If Dispatcharr cannot provide true instant live pause/rewind cleanly, evaluate one additional maintained PVR/DVR backend. Do not run a broad bakeoff.
Long-term native ChannelForge DVR remains optional post-product work. The integration boundary must make backend replacement possible.
6. Immediate sequencing
Gate 0 — finish the work already in flight
Owner: current #182 workstream
Before new implementation branches
This avoids abandoning nearly complete Alpha.1 work and avoids contaminating the new architecture with an unclosed source-set branch.
7. First three new product slices
These are the first implementation slices after Gate 0. They are intentionally small and vertical.
Slice 1 — One Guide canonical read model
Primary issues: #186, #191, #193
No provider credentials yet. No playback mutation yet.
Deliver:
Do not add a second accepted-state authority.
Do not make XMLTV the internal canonical model.
Exit proof
A test client can query a deterministic local guide, open category views instantly, and see one canonical event with multiple fixture offerings.
Slice 2 — SER8 10-foot shell + platform/composition proof
Primary issues: #188, #192, #193, #194
Parallel with late Slice 1 once the read API shape is stable.
Deliver:
Use the existing React/Vite work where it saves time. Do not force the existing desktop/workbench layout into the TV surface if it harms the 10-foot UX.
Exit proof
An untrained tester can use Harmony to open Wrestling, inspect an event, return Home, and navigate Live Now without coaching.
Slice 3 — First real integrated couch vertical
Primary issues: #189, #187, #67, #70, #68
Prove integration, not provider breadth.
Use the smallest provider set that proves all architecture:
Deliver:
Exit proof
From ChannelForge on the SER8:
8. Parallel work lanes after Slice 1 contracts stabilize
Use bounded parallelism.
Lane A — Guide Intelligence
#186, #191, #28/#121
Lane B — Provider Connections
#189, #187
Lane C — Living-Room Client
#188, #194
Lane D — Playback / Composition / DVR
#67, #68, #192
Lane E — Performance / Reliability
#193, #35, #36
No lane may independently redefine canonical identities or accepted-state semantics.
9. Component adoption gate
Before adopting an off-the-shelf component, verify:
Reuse now, replace later if needed.
10. Guide-quality priority
When schedule pressure appears:
Do not ship a broad but unreliable guide.
11. Cost-control execution policy
Every nontrivial slice begins in planning mode.
Default to:
Escalate reasoning/model cost only for genuine architecture, security, conflicting evidence, or failed lower-cost paths.
12. October target
By 2026-10-31, require:
The October target is deliberately aggressive because the March 2027 deadline leaves no room for an architecture-only month.
13. Stop conditions
Stop and escalate before implementation if:
14. Definition of planning complete
Planning V1 is complete when:
Any later plan change must identify the new evidence that makes this plan wrong or incomplete.
Jumpstile commentedon Sep 27, 2026
TRUE_PLANNING_V1 addendum — distributed deployment
Product-owner clarification after the initial planning pass:
Planning consequence:
The first new product slices remain One Guide -> SER8 shell -> real couch vertical, but Slice 2 now connects to a remote backend across the #196 contract rather than assuming local engine co-residency.
Jumpstile commentedon Sep 27, 2026
Planning addendum: #197 is future/medium priority and does not expand the six-month scope. March 2027 requires one excellent certified SER8 client. Current architecture must merely avoid unnecessary lock-in so Apple TV, Roku, Android TV/Shield, and other clients can be added later against the same backend/client contract.
Jumpstile commentedon Sep 27, 2026
TRUE_PLANNING_V1 sequencing correction: Gate 0 (#182) is no longer a global stop condition.
PR #182 must still pass its required owner/device smoke before merge, but while that narrow gate is pending, independent release-driving work may proceed in parallel where it does not depend on #182's unmerged behavior.
Immediate allowed parallel work:
Do not consume unmerged #182 behavior as if it were main. Rebase/reconcile later as needed.
Project rule: never idle the whole program because one lane is waiting.
Jumpstile commentedon Sep 27, 2026
Scope-control refinement: anti-overengineering is now explicit under #195. The six-month plan should always prefer the smallest complete vertical slice, one working provider before broad provider frameworks, one certified SER8 client before multi-platform implementations, and one proven DVR backend before custom DVR work. Future extensibility may shape cheap boundaries but must not justify speculative infrastructure.
Jumpstile commentedon Sep 27, 2026
Planning refinement: #195 now permits selective higher-capability advisor review for genuinely hard architecture/security/debugging decisions. Use one focused advisor first; do not create broad multi-agent review swarms. Advisor use must support the March 2027 target and cost discipline rather than becoming another process layer.
Jumpstile commentedon Sep 27, 2026
TRUE_PLANNING_V1 refinement: the Intelligence Engine is the product core and canonical source of truth. Provider adapters, XMLTV/M3U, sports schedules, DVR backends, and clients remain evidence/integration/projection layers. #36 may introduce SQLite when the One Guide vertical slice demonstrates the need; prefer SQLite first for simplicity and speed, with PostgreSQL only if measured concurrency/scale proves it necessary. Do not delay vertical slices for speculative database architecture.
Jumpstile commentedon Sep 30, 2026
2026-09-30 coordination state: PR #199 merged at
f20c7f034bb473ef196cddeb9ffaa2399675c227; #198 closed completed; stale screenshot PR #168 closed; expanded taxonomy proceeds under #191; #200 may proceed in parallel in its own lane. Schedule remains AT RISK, so parallel #191/#200 is the current critical-path strategy.Jumpstile commentedon Sep 30, 2026
Active lane registry — 2026-09-30
All ChannelForge sessions use
C:\Temp\CHANNELFORGE-AUTHORITATIVE-STATE.txtas the current coordination state. No lane may clean, redirect, or overlap another without checking that state first.Jumpstile commentedon Nov 13, 2026
Phase 0 update (Nov 13): test baseline on main is 882 passed, 0 failed, 1 skipped. All 77 open issues are mapped with a dependency map and order in docs/planning/PHASE-0-FINDINGS.md (merged, main 8c5985c). 51 issues have a milestone, 26 do not; those 26 get a milestone or are closed once Phase 1 starts. The March 31, 2027 date is still unconfirmed.
Co-Authored-By: Claude Sonnet 5.5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01NzHAcnJaQLFSmFX9BoM2UE
Jumpstile commentedon Nov 17, 2026
Milestone reorder (2026-11-16, approved by the owner). Same issues, new order and names. Nothing was deleted.
The old Milestone 2 is closed and marked retired. ROADMAP.md is updated in PR #262 with a mapping from the old numbers.
https://claude.ai/code/session_01NzHAcjThVoUGWWfXrYWsNh