Upstream Integration Governor

Upstream Integration Governor

Turn upstream changes into bounded, evidence-backed, user-decidable stages and, only after approval, reversible WebHTV changes. Do not use this long workflow for an ordinary App bug unless it actually crosses an upstream/native contract.

For maintenance of this Skill, governance text, or task-guard wording, follow the root AGENTS.md governance-maintenance fast path. Do not invoke this upstream workflow, load its references, research best practices, forward-test, or create a temporary repository. Make one bounded patch and one combined validation pass, then stop.

Select one bounded lane first

• assessment: use a 45-minute progress-review cadence, each batch focused on one related function cluster or at most 25 straightforward commits. Only the assessment document and explicit governance/evidence files may change.
• upstream: use a 45-minute progress-review cadence around one approved atomic implementation unit. Declare all source, lock, patch, artifact, App, test, and documentation paths before editing.
• Never silently turn assessment into implementation or a narrow App fix into upstream research.

Start bash .codex/scripts/task_guard.sh using the matching lane. Check it after each repository/query batch and before a build, native command, or large diff. At 70% of a cadence, checkpoint before opening new work. At the boundary, preserve concrete progress; continue a converging route with one bounded next action, or replan a stalled/repeated route and immediately resume. Cadences never cap total task time or review count. Never lower verification quality, call an unverified candidate complete, or abandon the requested result because time elapsed.

Stable task IDs and one-document ownership

• Use docs/upstream-player-dependency-merge-assessment-2026-08-20.md as the stable task index and exhaustive commit ledger. Resolve or allocate the task ID there before opening task-specific documentation.
• Preserve the established families: E*/E*-* for Exo, E-SP* for Exo performance, P*/P*-* for MPV, and C*/C*-* for common work. Assigned IDs are immutable and must not be renumbered or reused.
• A started task owns exactly one docs/<TASK-ID>-<slug>.md. Put research, alternatives, recommendation, approval, implementation, repeated corrections, validation, full commit/tag records, rollback, current status, and the one next action in that file.
• Never create additional plans/, assessment, implementation, fix, or dated continuation documents for the same task. Continue appending to its unique file. The master assessment is the only exception and only supplies the cross-task index and complete commit ledger.

Build or refresh an upstream assessment ledger

Use this mode when the user asks to梳理 new upstream updates, rebuild the player dependency merge plan, or produce a document comparable to the existing dated assessment.

1. Discover the repository graph from the prior assessment, .gitmodules, lock files, source/version manifests, Gradle/native build scripts, patch directories, artifact provenance, and repository documentation. Include direct upstreams, WebHTV forks, dependency/source repositories, and packaging repositories that can change the shipped player behavior; record why each repository is in scope and how revisions flow between them.
2. Freeze exact local and upstream baselines before judging commits: repository URL/path, branch, previous assessed head, current head, ancestry, relevant lock or artifact hash, access date, and any proxy or source-access limitation. Never infer a missing hash from conversation memory.
3. Enumerate the complete commit range in each repository using full 40-character IDs. Inspect actual diffs, parents, tests, follow-ups, reverts, rebases/equivalents, downstream consumers, and final-tree behavior. Give every commit one explicit disposition such as already implemented, partially implemented, superseded, irrelevant, candidate, blocked, or implemented; do not omit merge, cleanup, or low-value commits merely because they are inconvenient.
4. Map cross-repository chains rather than presenting isolated lists. Show which source commit feeds which fork/lock/patch/artifact/App change, which commits are companions, and which ordering or binary rebuild dependency makes them one functional stage.
5. Compare the ledger with current WebHTV code and Git history before creating tasks. Existing local behavior is the baseline contract; detect equivalent implementations, later fixes, partial coverage, and code paths that make an upstream change unreachable. Mark covered or meaningless work as ignored instead of manufacturing a task.
6. Preserve a closed historical assessment. When a materially new upstream wave begins, create docs/upstream-player-dependency-merge-assessment-YYYY-MM-DD.md, link its predecessor, and record the new baselines; when continuing the same active wave, update its existing dated document. The document must remain the exhaustive cross-task index and link each actionable item to its single docs/<TASK-ID>-<slug>.md file.
7. Organize actionable work into reversible Exo, MPV, and common stages with the selection order Exo -> MPV -> common. For every stage record the user-visible playback capability, repository/commit chain, current coverage, benefits, risks and disadvantages, compatibility/performance/package-size impact, best-practice evidence, WebHTV adaptation, recommendation, acceptance criteria, verification, rollout, rollback, and next action.

For a request that only asks for the next task, do not mutate the ledger or code. Recover the current state, identify exactly one unambiguous next candidate, and return the following decision packet in ordinary user-facing language:

任务编号和名称：
所属分类：Exo / MPV / 通用
要实现的实际能力：
当前项目已有实现：
涉及仓库及完整 commit ID：
收益：
缺点与风险：
与现有功能的关系：
建议：实施 / 暂缓 / 忽略
最小实施步骤：
预计需要的验证：

Stop after that packet. Do not implement until the user explicitly approves the candidate. When estimating approved work, report current-agent wall-clock execution time and separate code work, native/Gradle build time, device or user-dependent validation, and commit/tag/document closure when those phases apply.

Mandatory best-practice review before implementation

This gate applies to every proposed upstream merge stage and every material new player/dependency requirement. It is not optional merely because a commit appears small or its upstream title sounds authoritative.

1. Before implementation, create or update the unique docs/<TASK-ID>-<slug>.md and link it from the assessment index. Its best-practice section is the durable decision record; a separate plans/ file or conversation summary is insufficient.
2. Perform a focused but deep external review. Search all applicable categories: exact upstream source, history, tests, and follow-ups; official platform/specification/project documentation; PRs, issues, reverts, and maintainer discussions; mature related-project implementations and tests; and relevant academic papers, technical posts, blogs, benchmarks, or field reports. Inapplicable categories must be explicitly marked with a reason.
3. Inspect complete sources and revisions, not snippets. Record full commit IDs, URLs/paths, access dates, evidence grade, relevant code or excerpt, applicability to WebHTV, caveats, and how each source changes the decision. Research must use the configured proxy when needed and must not be represented as complete when network/source access failed.
4. Review the current WebHTV code before choosing a port: concrete files/symbols, callers and data flow, existing equivalent/partial implementations, local patches and safeguards, build/package reachability, and relevant tests or device evidence.
5. Compare no change, unmodified upstream, and a WebHTV-adapted design. The plan must state whether the upstream design should be optimized, corrected, supplemented, completed, or rejected for this workload, with explicit tradeoffs and acceptance/rollback criteria.
6. Pause for user approval after the plan is decision-ready. No code, lock, build, patch, or binary edit is allowed before approval. Keep the investigation bounded by one decision-shaped question; stop when more sources cannot change the decision and record any remaining uncertainty as a gate.