| name | upstream-contribution |
| description | Contribute a verified AALC behavior or fix from the downstream fork to upstream, including isolated worktree setup, porting-strategy selection, upstream-native rewriting, contamination and style review, regression tests, pull-request review and CI iteration, and post-merge downstream reconciliation. Use whenever preparing, opening, updating, or following through on an upstream contribution. |
AALC Upstream Contribution
Treat an upstream contribution as a behavior port, not as a downstream commit transfer. The job is complete only when the upstream-native change has passed review, the final upstream result is known, and downstream reconciliation has been checked.
Required outcome
Produce all of the following:
- A written behavior contract and provenance record.
- A named branch in an isolated worktree based on the current upstream target.
- An upstream-native implementation with no accidental fork coupling.
- Relevant upstream-native regression coverage when practical.
- A clean
code-review result using the upstream profile.
- Passing local checks and PR checks, or an explicit report of remaining failures.
- Resolution of actionable PR feedback and re-review after every update.
- Post-merge or post-close reconciliation against the final upstream state and the downstream fork.
- A review finding ledger showing why every requested change was fixed, rejected, split, or escalated.
Opening or updating a PR is an intermediate state, not successful completion.
Safety and authority
- Preserve the original workspace and its uncommitted or untracked files.
- Perform implementation, commits, rebases, and conflict work only inside the contribution worktree.
- Do not resolve conflicts with blanket
ours or theirs choices.
- Never read or print credentials. Use existing authenticated Git/GitHub tooling.
- Treat push, PR creation, review replies, and remote edits as external writes. Execute only the scope the user authorized; otherwise stop at the next external-write gate with a complete report.
- Do not force-push unless the user explicitly authorizes it after the exact branch and reason are shown.
Progressive references
Read only the reference needed for the current phase:
Phase 1: Establish facts without writing
- Inspect
git status --short, remotes, current branch, and candidate commits or diff.
- Fetch the target remote and identify the exact upstream base branch and commit.
- Read the downstream issue, failure evidence, relevant tests, and the full changed functions with their callers.
- Inspect the same APIs and adjacent implementation in the upstream tree.
- Write a behavior contract:
Trigger:
Observed failure:
Expected behavior:
Required state transition:
Regression oracle:
Non-goals:
User decisions and validation exceptions:
Downstream provenance:
Upstream base commit:
Do not use the downstream diff as the specification. If the observed behavior cannot be explained, pause implementation and report the evidence gap.
Phase 2: Classify every changed concern
Build an explicit scope table before porting:
| Concern or hunk | Disposition | Reason |
|---|
| Behavior required by the contract | port | Required upstream behavior |
| Regression test | port or rewrite | Match upstream test conventions |
| Downstream-only config/debug/release/tooling | exclude | Fork infrastructure |
| Refactor not required for the behavior | exclude | Unrelated scope |
| API adaptation | rewrite | Match upstream interfaces and defaults |
Do not categorically exclude tests/. If upstream has automated tests and the behavior is testable, add or adapt a focused regression test. Do not copy downstream-only fixtures or manual test/ scripts when upstream lacks their dependencies.
Phase 3: Create the isolated branch
Follow references/git-isolation.md. The worktree must be attached to a named branch created from the fetched upstream target, for example:
$branch = "upstream-contrib/<short-name>"
$path = ".worktrees/upstream-contribution/<short-name>"
git worktree add -b $branch $path upstream/main
Immediately verify:
git -C $path branch --show-current
git -C $path merge-base --is-ancestor upstream/main HEAD
git -C $path status --short
A detached HEAD, unexpected base, or pre-existing changes blocks implementation.
Phase 4: Select and execute the porting strategy
Use the decision rules in references/porting-strategy.md:
- Exact transfer only when the whole commit is behaviorally and structurally compatible.
- Apply-without-commit plus adaptation when the change is mostly compatible.
- Behavior-based rewrite when histories, APIs, style, or responsibilities diverge. This is the default for interwoven fork code.
After applying code:
- Compare the implementation with adjacent upstream code, not downstream neighbors.
- Remove fork provenance that does not help upstream maintainers.
- Add the smallest upstream-native regression test that fails before and passes after the fix, when practical.
- Stage only the classified scope. Never use
git add -A in a mixed worktree.
Phase 5: Review before commit
Run the code-review skill against the staged diff and explicitly request its upstream-contribution profile. It must use references/upstream-style-review.md and inspect complete changed functions and relevant upstream call sites.
Resolve all confirmed High/Critical findings and all upstream-contamination findings before committing. For lower-severity observations, either simplify the code or record why the upstream pattern justifies it.
Do not convert raw reviewer output directly into an implementation task. Use references/review-convergence.md to assign stable finding IDs, verify eligibility against the behavior contract, and identify scope expansion first. A pre-existing path is not a contribution blocker unless the current diff newly invokes it, changes it, or relies on the violated property.
Run the deterministic scope check:
& .agents/skills/upstream-contribution/scripts/validate_contribution.ps1 `
-BaseRef upstream/main `
-TargetRef HEAD `
-IncludeIndex
Before the first commit, also inspect:
git diff --cached --stat
git diff --cached
Commit with an upstream-native message. Preserve downstream provenance in the work report or PR body when useful; do not force Backport of ... into an upstream commit when it reads as fork-centric history.
Phase 6: Verify the branch
Review the entire contribution, not only the last commit:
git log --oneline upstream/main..HEAD
git diff upstream/main...HEAD --stat
git diff upstream/main...HEAD
Run the narrowest sufficient upstream checks:
- syntax or import checks for changed Python files;
- targeted Ruff checks without cleaning unrelated legacy warnings;
- relevant automated regression tests;
- build, i18n, update-protocol, or asset checks when those areas changed.
Re-run validate_contribution.ps1 without -IncludeIndex against the committed branch.
Re-run code-review on the final branch diff after fixes, passing the contract revision, complete finding ledger, previous reviewed SHA, and delta. A passing test suite does not replace upstream-style review.
If two consecutive re-reviews produce new blockers that require architectural expansion, or a proposed fix reverses an earlier review decision, stop adding patches. Preserve the worktree and choose rewrite, explicit scope expansion, a split contribution, or deferral before continuing.
Phase 7: Open and iterate the PR
At the authorized external-write gate, push the named branch and open the PR against the verified upstream repository and base. Use a literal here-string or notes file for multiline Markdown in PowerShell.
Then follow references/pr-lifecycle.md until one of these terminal remote states is reached:
- merged;
- closed without merge with a documented reason;
- genuinely blocked on upstream action, with current CI and review state reported.
For every pushed update:
- Fetch the current upstream base and determine whether the branch is stale.
- Re-run affected checks and the upstream-profile review.
- Inspect new CI results and unresolved review threads.
- Reply only after the code and evidence support the response.
- Confirm that the remote PR head matches the locally validated commit.
Keep the same finding ledger through local and remote review. Do not reopen a verified or rejected item without recording new evidence, and do not repeatedly convert an explicit user-approved validation exception into a new blocker.
Do not report completion merely because feedback was answered or a new commit was pushed.
Phase 8: Reconcile the final upstream result
Follow references/downstream-reconciliation.md after merge, maintainer edits, squash/rebase merge, or closure.
At minimum:
- Fetch upstream and identify the final upstream commit or the final rejected state.
- Compare final upstream behavior with the original behavior contract.
- Compare that final behavior with downstream current code.
- Use
downstream-sync when upstream contains a fix or refinement not represented downstream.
- Run the downstream regression oracle and relevant checks.
- Record whether the original downstream commit can remain, should be replaced, or needs a follow-up cleanup.
Final report
## 上游贡献结果
- 行为契约：
- Worktree / branch：
- Upstream base：
- Porting strategy：exact / adapt / rewrite
- 贡献提交与 PR：
- 上游风格审阅：
- 审阅收敛：contract revision、finding ledger 与仍开放项
- 本地验证：
- CI 与评审线程：
- 最终上游状态：merged / closed / blocked
- 下游对账：already equivalent / synced final upstream / follow-up required
- 剩余风险：
Every claimed success must name the command, check, review state, or commit that proves it.
