[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M69BS54V1THPSKYAA7VFSBAY":3,"skill-same:01M69BS54V1THPSKYAA7VFSBAY":116},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":47,"linkOnly":48,"markdownContent":49,"markdownBody":50,"frontMatter":51,"refName":52,"commitSha":53,"skillDirectory":54,"forksCount":55,"repositoryHtmlUrl":56,"repositoryHomepageUrl":57,"ownerHtmlUrl":58,"ownerBlogUrl":59,"ownerDescription":60,"updatedAt":61,"install":62,"resources":75},"01M69BS54V1THPSKYAA7VFSBAY","upstream-sync",null,"Periodically sync new commits from microsoft\u002Fterminal into this manually-forked intelligent-terminal repo by cherry-picking commit-by-commit onto a dated sync branch, auto-skipping revert pairs and empty commits, auto-resolving known take-upstream files, and stopping cleanly on genuine conflicts. The agent (you, reading this file) is the orchestrator — the PowerShell scripts are atomic operations you invoke one at a time. Use when the user asks to \"sync upstream\", \"pull from microsoft\u002Fterminal\", \"run upstream sync\", \"catch up to upstream\", or wires this into a scheduler (weekly\u002Fdaily). Designed to be safe under repeated unattended runs.","microsoft\u002Fintelligent-terminal","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M69BR4043X0X0KRBRZVGJP2V",2214,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fintelligent-terminal\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fupstream-sync\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,9,46],"sync","upstream sync","upstream","auto","new","when","invoke","catch","weekly","you","time","conflicts","files","up","terminal","orchestrator","one at a time","branch","powershell","run","sync upstream","commit","safe","2026-11-10 10:12:30",false,"---\r\nname: upstream-sync\r\ndescription: 'Periodically sync new commits from microsoft\u002Fterminal into this manually-forked intelligent-terminal repo by cherry-picking commit-by-commit onto a dated sync branch, auto-skipping revert pairs and empty commits, auto-resolving known take-upstream files, and stopping cleanly on genuine conflicts. The agent (you, reading this file) is the orchestrator — the PowerShell scripts are atomic operations you invoke one at a time. Use when the user asks to \"sync upstream\", \"pull from microsoft\u002Fterminal\", \"run upstream sync\", \"catch up to upstream\", or wires this into a scheduler (weekly\u002Fdaily). Designed to be safe under repeated unattended runs.'\r\nlicense: MIT\r\n---\r\n\r\n# Upstream Sync (microsoft\u002Fterminal → intelligent-terminal)\r\n\r\nCherry-pick commit-by-commit from `https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fterminal`\r\ninto this fork, preserving per-commit attribution, auto-skipping picks\r\nthat cancel each other out, and stopping cleanly the moment a\r\nhuman-judgment conflict appears.\r\n\r\n**You — the agent reading this file — are the orchestrator.** Each step\r\nin the run is a single atomic call into one of the `scripts\u002F*.ps1` files.\r\nThere is intentionally no PowerShell driver, because every interesting\r\ndecision (build-fix vs. open stuck issue, retry vs. bail, finalize vs.\r\ndry-run) wants LLM judgment the operator can audit in your transcript.\r\n\r\n## When to Use This Skill\r\n\r\n- User asks to \"sync upstream\", \"pull from microsoft\u002Fterminal\", \"catch up to upstream\", or \"run upstream sync\".\r\n- A scheduler invokes the agent on a weekly\u002Fdaily cadence.\r\n- The previous run left an `upstream-sync-stuck` labeled issue open and the human has finished resolving the conflict — **close the issue** (that IS the lock-clear signal) and re-run.\r\n\r\n## When NOT to Use This Skill\r\n\r\n- User wants a **one-shot rebase** of a single feature branch onto upstream — that's a normal `git rebase`, not this skill.\r\n- An `upstream-sync-stuck` labeled issue is open on `microsoft\u002Fintelligent-terminal` — do not re-run; resolve the conflict on the stuck branch first, then close the issue.\r\n\r\n## Prerequisites\r\n\r\n- `git` 2.38+ (for `cherry-pick --keep-redundant-commits`), `gh` CLI authenticated against `microsoft\u002Fintelligent-terminal` (needs push to `upstream-sync\u002F*` topic branches + issue\u002Flabel create), PowerShell 7+ (`pwsh`) on PATH.\r\n- **`origin` MUST point at `microsoft\u002Fintelligent-terminal`.** All scripts push to `origin` and pass `-R microsoft\u002Fintelligent-terminal` explicitly. Verify with `git remote -v` before running.\r\n- **Full git history on `origin\u002Fmain`** (no shallow clone). Watermark discovery walks up to 5000 commits scanning for `cherry picked from commit \u003Csha>` trailers. In CI, use `actions\u002Fcheckout@v4` with `fetch-depth: 0`.\r\n- Windows build host with Visual Studio 2022, Windows SDK, `vswhere`, and `tools\\razzle.cmd` \u002F `bz`. Build is a hard gate before finalize.\r\n- **No `state.json` to bootstrap.** Watermark = newest `(cherry picked from commit \u003Csha>)` trailer on `origin\u002Fmain`. If the fork has never used `cherry-pick -x`, run the one-time [First-time sync](.\u002Freferences\u002Frecovery-procedures.md#first-time-sync-seeding-the-watermark).\r\n\r\n## State Model (no state file)\r\n\r\nEvery persistent fact lives in the source that owns it:\r\n\r\n| Question | Source of truth |\r\n|---|---|\r\n| Last-synced upstream commit? | Newest `(cherry picked from commit \u003Csha>)` trailer on `origin\u002Fmain` whose target is reachable from `upstream\u002Fmain`. Derived by [`02-compute-pending.ps1`](.\u002Fscripts\u002F02-compute-pending.ps1). |\r\n| What's pending? | `git log --cherry-pick --right-only --no-merges origin\u002Fmain...upstream\u002Fmain`, drop SHAs at\u002Fbefore the watermark. Patch-id based, so a picked-then-reverted commit correctly re-appears. |\r\n| Is the scheduler locked? | Any open issue with the `upstream-sync-stuck` label on `microsoft\u002Fintelligent-terminal`. Closing it IS the lock-clear signal. |\r\n| Where do build logs go? | `Generated Files\u002Fupstream-sync\u002F\u003CYYYY-MM-DD>\u002F` — gitignored by the repo root's `**\u002FGenerated Files\u002F`. Never committed. |\r\n\r\n### Why cherry-pick (not rebase or merge)\r\n\r\n- **Rebase upstream\u002Fmain** — ❌ fork history contains old \"Merge upstream\" commits; rebase replays them and explodes conflicts (verified failure on sister repo).\r\n- **Merge upstream\u002Fmain** — ⚠️ works, but collapses the whole sync into one blob commit, killing per-commit review and `git bisect`.\r\n- **Cherry-pick commit-by-commit** — ✅ preserves authorship + per-commit content, allows mechanical revert-pair skipping, produces a reviewable PR.\r\n\r\n## Run a sync\r\n\r\nEight-step orchestration. Full commands, JSON contracts, and\r\nfailure-handling for every step are in\r\n[`references\u002Frun-a-sync.md`](.\u002Freferences\u002Frun-a-sync.md). The flow:\r\n\r\n```\r\n1. Preconditions (clean tree, on main FF, no open stuck issue)\r\n2. Create branch  upstream-sync\u002F\u003CUTC-yyyy-MM-dd-HHmmss-rand4>\r\n3. Fetch upstream (verify owner\u002Frepo identity of the `upstream` remote)\r\n4. Compute pending     ← scripts\u002F02-compute-pending.ps1  (→ JSON)\r\n5. Cherry-pick loop    ← scripts\u002F03-cherry-pick-one.ps1 per SHA  (→ JSON)\r\n       picked \u002F skipped-empty → continue\r\n       stuck → 5a (push branch, file upstream-sync-stuck issue, EXIT)\r\n6. (No commits picked? exit clean.)\r\n       before build: re-pin build\u002Fpgo\u002FTerminal.PGO.props if upstream bumped\r\n       its Windows Terminal Major.Minor (else PGO build fails)\r\n7. Build               ← scripts\u002F04-try-build.ps1  (→ JSON)\r\n       build-ok → step 8\r\n       build-failed → ONE focused fix commit, re-build; else 7a\r\n       build-inconclusive → 7a\r\n   7a. Surface failure to operator, EXIT (no issue filed for build failures)\r\n8. Finalize: push, `gh pr create`, optional `gh pr merge --rebase --auto`\r\n```\r\n\r\n**Key invariants** (the agent MUST hold these — full rationale in the runbook):\r\n\r\n- **Atomic per-commit.** Each pick is one commit on the sync branch carrying the upstream author\u002Fdate and the `(cherry picked from commit \u003Csha>)` trailer. Never amend across picks.\r\n- **Stuck → exit clean.** On a Tier-3 conflict (script returns `status: \"stuck\"`), do NOT continue past it — push the branch, file the labeled issue, exit. The human resolves on the stuck branch, merges (no squash), closes the issue.\r\n- **One build-fix commit, max.** Build-blocking fixes land as exactly one extra commit on the sync branch. Anything bigger → exit; the operator pushes a manual fix or runs a follow-up PR.\r\n- **Never squash-merge the sync PR.** Squashing destroys per-commit attribution AND the trailer the next sync uses as its watermark. The PR body banner warns reviewers; the recipe arms `--rebase --auto`.\r\n\r\n## Recovery procedures (rare)\r\n\r\nDirect-to-main escape hatch, first-time watermark seeding, squash-merge\r\nrecovery: [`references\u002Frecovery-procedures.md`](.\u002Freferences\u002Frecovery-procedures.md).\r\nEach requires explicit operator action.\r\n\r\n## After-PR review handling — fix-in-PR vs. follow-up PR\r\n\r\nOnce the sync PR is open, reviewers (Copilot + humans) will comment.\r\n**Only build-blocking fixes** belong on the sync branch as one focused\r\nextra commit. Everything else — code-quality, logic-bug suggestions,\r\ntranslation corrections, spelling-allowlist migrations, doc nits, design\r\nfeedback — goes into a **follow-up PR** that targets the sync branch\r\n(not `main`). The cherry-pick PR must stay reviewable as \"per-commit,\r\nfaithful to upstream + minimum must-merge delta\".\r\n\r\nFull rubric, worktree mechanics, PR-body template:\r\n[`references\u002Ffollow-up-pr.md`](.\u002Freferences\u002Ffollow-up-pr.md).\r\n\r\n## Gotchas\r\n\r\n- **Never squash-merge the sync PR.** Squashing destroys per-commit\r\n  attribution AND collapses the trailers the next run uses as its\r\n  watermark. The PR body opens with a banner; step 8 arms\r\n  `gh pr merge --rebase --auto`.\r\n- **Never strip the `(cherry picked from commit \u003Csha>)` trailer** when\r\n  hand-resolving a stuck pick. That trailer IS the watermark.\r\n- **Never rebase `upstream\u002Fmain` onto this fork.** Use cherry-pick —\r\n  rebase replays old \"Merge upstream\" commits and explodes.\r\n- **Don't amend substantive review fixes into the sync PR.** Only\r\n  build-blocking fixes (max one extra commit). Everything else → follow-up PR.\r\n- **`.github\u002Fworkflows\u002Fspelling2.yml` always conflicts** and is always\r\n  \"take upstream wholesale\". The Tier-0 list in\r\n  [`references\u002F03-known-conflicts.md`](.\u002Freferences\u002F03-known-conflicts.md)\r\n  handles it — extend the list when you find the next file with this pattern.\r\n- **`gh pr create` on Windows can fail with \"Head sha can't be blank\"**\r\n  on freshly-pushed branches. The step-8 recipe wraps it in a 3× retry.\r\n  Do not \"fix\" it to use `--head \u003Cowner>:\u003Cbranch>` (that points `gh` at a fork).\r\n- **Cherry-pick over `git revert`-style commits is intentional, not\r\n  skipped.** We only skip revert-pairs where **both** sides are inside\r\n  the pending range. A revert of an already-merged commit must land —\r\n  otherwise the fork diverges silently.\r\n- **Single-host scheduler.** The stuck-lock is a read-then-check gate,\r\n  not an atomic lease. Run from ONE host. For multi-host fan-out, layer\r\n  atomic locking on top (GitHub Actions `concurrency: upstream-sync` is\r\n  easiest).\r\n- **CRLF\u002FLF on manifest files.** Cherry-picks preserve upstream endings,\r\n  but Tier-2 LLM-touched resolutions on `.yml`\u002F`.xml`\u002F`.csproj`\u002Fwinget\r\n  manifests may downgrade to LF. Re-normalize before staging — see\r\n  [`references\u002F03-conflict-triage.md`](.\u002Freferences\u002F03-conflict-triage.md#line-endings).\r\n- **PGO pin follows upstream.** `build\u002Fpgo\u002FTerminal.PGO.props` hard-pins the\r\n  PGO database to upstream's Windows Terminal `Major.Minor` (our `custom.props`\r\n  stays `0.1`, so it can't be derived). When a sync bumps the upstream version,\r\n  re-pin those two values or the build fails with `Could not find matching PGO\r\n  package`. Step 7's pre-build check covers this.\r\n\r\n## Troubleshooting\r\n\r\n| Issue | Solution |\r\n|---|---|\r\n| `02-compute-pending.ps1` throws \"No 'cherry picked from commit' trailer …\" | Fork has never used `cherry-pick -x` yet. Run the one-time [First-time sync](.\u002Freferences\u002Frecovery-procedures.md#first-time-sync-seeding-the-watermark). |\r\n| Stuck issue prevents new run | Resolve on the stuck branch, open + merge a PR (keep the trailer, don't squash), then **close the stuck issue**. The next scheduler tick proceeds. |\r\n| `03-cherry-pick-one.ps1` returns `\"skipped-empty\"` | Expected for upstream no-op commits and fork-already-applied patches. The loop skips and continues. |\r\n| Same file conflicts every run | Add it to [`references\u002F03-known-conflicts.md`](.\u002Freferences\u002F03-known-conflicts.md) with the right strategy (`take-upstream` or `take-ours`; `union` is reserved and currently escalates instead of auto-resolving). |\r\n| `gh pr create` returns \"Head sha can't be blank\" | Step 8 retries 3×. On slow networks, the operator may need a manual second run. |\r\n\r\n## References\r\n\r\n- [`references\u002Frun-a-sync.md`](.\u002Freferences\u002Frun-a-sync.md) — full eight-step procedure with commands.\r\n- [`references\u002F03-conflict-triage.md`](.\u002Freferences\u002F03-conflict-triage.md) — Tier 0\u002F1\u002F2\u002F3 conflict-resolution rubric.\r\n- [`references\u002F03-known-conflicts.md`](.\u002Freferences\u002F03-known-conflicts.md) — files with fixed Tier-0 resolutions.\r\n- [`references\u002Ffollow-up-pr.md`](.\u002Freferences\u002Ffollow-up-pr.md) — fix-in-PR vs. follow-up PR rubric and worktree workflow.\r\n- [`references\u002Frecovery-procedures.md`](.\u002Freferences\u002Frecovery-procedures.md) — direct-to-main, first-time seed, squash-merge recovery.\r\n- [`scripts\u002F02-compute-pending.ps1`](.\u002Fscripts\u002F02-compute-pending.ps1) — derive watermark + pending list (no state file).\r\n- [`scripts\u002F03-cherry-pick-one.ps1`](.\u002Fscripts\u002F03-cherry-pick-one.ps1) — cherry-pick one SHA with author\u002Fdate pinning + Tier-0\u002FTier-1.\r\n- [`scripts\u002F04-try-build.ps1`](.\u002Fscripts\u002F04-try-build.ps1) — run `bz no_clean`; log to `Generated Files\u002F...`.\r\n","# Upstream Sync (microsoft\u002Fterminal → intelligent-terminal)\r\n\r\nCherry-pick commit-by-commit from `https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fterminal`\r\ninto this fork, preserving per-commit attribution, auto-skipping picks\r\nthat cancel each other out, and stopping cleanly the moment a\r\nhuman-judgment conflict appears.\r\n\r\n**You — the agent reading this file — are the orchestrator.** Each step\r\nin the run is a single atomic call into one of the `scripts\u002F*.ps1` files.\r\nThere is intentionally no PowerShell driver, because every interesting\r\ndecision (build-fix vs. open stuck issue, retry vs. bail, finalize vs.\r\ndry-run) wants LLM judgment the operator can audit in your transcript.\r\n\r\n## When to Use This Skill\r\n\r\n- User asks to \"sync upstream\", \"pull from microsoft\u002Fterminal\", \"catch up to upstream\", or \"run upstream sync\".\r\n- A scheduler invokes the agent on a weekly\u002Fdaily cadence.\r\n- The previous run left an `upstream-sync-stuck` labeled issue open and the human has finished resolving the conflict — **close the issue** (that IS the lock-clear signal) and re-run.\r\n\r\n## When NOT to Use This Skill\r\n\r\n- User wants a **one-shot rebase** of a single feature branch onto upstream — that's a normal `git rebase`, not this skill.\r\n- An `upstream-sync-stuck` labeled issue is open on `microsoft\u002Fintelligent-terminal` — do not re-run; resolve the conflict on the stuck branch first, then close the issue.\r\n\r\n## Prerequisites\r\n\r\n- `git` 2.38+ (for `cherry-pick --keep-redundant-commits`), `gh` CLI authenticated against `microsoft\u002Fintelligent-terminal` (needs push to `upstream-sync\u002F*` topic branches + issue\u002Flabel create), PowerShell 7+ (`pwsh`) on PATH.\r\n- **`origin` MUST point at `microsoft\u002Fintelligent-terminal`.** All scripts push to `origin` and pass `-R microsoft\u002Fintelligent-terminal` explicitly. Verify with `git remote -v` before running.\r\n- **Full git history on `origin\u002Fmain`** (no shallow clone). Watermark discovery walks up to 5000 commits scanning for `cherry picked from commit \u003Csha>` trailers. In CI, use `actions\u002Fcheckout@v4` with `fetch-depth: 0`.\r\n- Windows build host with Visual Studio 2022, Windows SDK, `vswhere`, and `tools\\razzle.cmd` \u002F `bz`. Build is a hard gate before finalize.\r\n- **No `state.json` to bootstrap.** Watermark = newest `(cherry picked from commit \u003Csha>)` trailer on `origin\u002Fmain`. If the fork has never used `cherry-pick -x`, run the one-time [First-time sync](.\u002Freferences\u002Frecovery-procedures.md#first-time-sync-seeding-the-watermark).\r\n\r\n## State Model (no state file)\r\n\r\nEvery persistent fact lives in the source that owns it:\r\n\r\n| Question | Source of truth |\r\n|---|---|\r\n| Last-synced upstream commit? | Newest `(cherry picked from commit \u003Csha>)` trailer on `origin\u002Fmain` whose target is reachable from `upstream\u002Fmain`. Derived by [`02-compute-pending.ps1`](.\u002Fscripts\u002F02-compute-pending.ps1). |\r\n| What's pending? | `git log --cherry-pick --right-only --no-merges origin\u002Fmain...upstream\u002Fmain`, drop SHAs at\u002Fbefore the watermark. Patch-id based, so a picked-then-reverted commit correctly re-appears. |\r\n| Is the scheduler locked? | Any open issue with the `upstream-sync-stuck` label on `microsoft\u002Fintelligent-terminal`. Closing it IS the lock-clear signal. |\r\n| Where do build logs go? | `Generated Files\u002Fupstream-sync\u002F\u003CYYYY-MM-DD>\u002F` — gitignored by the repo root's `**\u002FGenerated Files\u002F`. Never committed. |\r\n\r\n### Why cherry-pick (not rebase or merge)\r\n\r\n- **Rebase upstream\u002Fmain** — ❌ fork history contains old \"Merge upstream\" commits; rebase replays them and explodes conflicts (verified failure on sister repo).\r\n- **Merge upstream\u002Fmain** — ⚠️ works, but collapses the whole sync into one blob commit, killing per-commit review and `git bisect`.\r\n- **Cherry-pick commit-by-commit** — ✅ preserves authorship + per-commit content, allows mechanical revert-pair skipping, produces a reviewable PR.\r\n\r\n## Run a sync\r\n\r\nEight-step orchestration. Full commands, JSON contracts, and\r\nfailure-handling for every step are in\r\n[`references\u002Frun-a-sync.md`](.\u002Freferences\u002Frun-a-sync.md). The flow:\r\n\r\n```\r\n1. Preconditions (clean tree, on main FF, no open stuck issue)\r\n2. Create branch  upstream-sync\u002F\u003CUTC-yyyy-MM-dd-HHmmss-rand4>\r\n3. Fetch upstream (verify owner\u002Frepo identity of the `upstream` remote)\r\n4. Compute pending     ← scripts\u002F02-compute-pending.ps1  (→ JSON)\r\n5. Cherry-pick loop    ← scripts\u002F03-cherry-pick-one.ps1 per SHA  (→ JSON)\r\n       picked \u002F skipped-empty → continue\r\n       stuck → 5a (push branch, file upstream-sync-stuck issue, EXIT)\r\n6. (No commits picked? exit clean.)\r\n       before build: re-pin build\u002Fpgo\u002FTerminal.PGO.props if upstream bumped\r\n       its Windows Terminal Major.Minor (else PGO build fails)\r\n7. Build               ← scripts\u002F04-try-build.ps1  (→ JSON)\r\n       build-ok → step 8\r\n       build-failed → ONE focused fix commit, re-build; else 7a\r\n       build-inconclusive → 7a\r\n   7a. Surface failure to operator, EXIT (no issue filed for build failures)\r\n8. Finalize: push, `gh pr create`, optional `gh pr merge --rebase --auto`\r\n```\r\n\r\n**Key invariants** (the agent MUST hold these — full rationale in the runbook):\r\n\r\n- **Atomic per-commit.** Each pick is one commit on the sync branch carrying the upstream author\u002Fdate and the `(cherry picked from commit \u003Csha>)` trailer. Never amend across picks.\r\n- **Stuck → exit clean.** On a Tier-3 conflict (script returns `status: \"stuck\"`), do NOT continue past it — push the branch, file the labeled issue, exit. The human resolves on the stuck branch, merges (no squash), closes the issue.\r\n- **One build-fix commit, max.** Build-blocking fixes land as exactly one extra commit on the sync branch. Anything bigger → exit; the operator pushes a manual fix or runs a follow-up PR.\r\n- **Never squash-merge the sync PR.** Squashing destroys per-commit attribution AND the trailer the next sync uses as its watermark. The PR body banner warns reviewers; the recipe arms `--rebase --auto`.\r\n\r\n## Recovery procedures (rare)\r\n\r\nDirect-to-main escape hatch, first-time watermark seeding, squash-merge\r\nrecovery: [`references\u002Frecovery-procedures.md`](.\u002Freferences\u002Frecovery-procedures.md).\r\nEach requires explicit operator action.\r\n\r\n## After-PR review handling — fix-in-PR vs. follow-up PR\r\n\r\nOnce the sync PR is open, reviewers (Copilot + humans) will comment.\r\n**Only build-blocking fixes** belong on the sync branch as one focused\r\nextra commit. Everything else — code-quality, logic-bug suggestions,\r\ntranslation corrections, spelling-allowlist migrations, doc nits, design\r\nfeedback — goes into a **follow-up PR** that targets the sync branch\r\n(not `main`). The cherry-pick PR must stay reviewable as \"per-commit,\r\nfaithful to upstream + minimum must-merge delta\".\r\n\r\nFull rubric, worktree mechanics, PR-body template:\r\n[`references\u002Ffollow-up-pr.md`](.\u002Freferences\u002Ffollow-up-pr.md).\r\n\r\n## Gotchas\r\n\r\n- **Never squash-merge the sync PR.** Squashing destroys per-commit\r\n  attribution AND collapses the trailers the next run uses as its\r\n  watermark. The PR body opens with a banner; step 8 arms\r\n  `gh pr merge --rebase --auto`.\r\n- **Never strip the `(cherry picked from commit \u003Csha>)` trailer** when\r\n  hand-resolving a stuck pick. That trailer IS the watermark.\r\n- **Never rebase `upstream\u002Fmain` onto this fork.** Use cherry-pick —\r\n  rebase replays old \"Merge upstream\" commits and explodes.\r\n- **Don't amend substantive review fixes into the sync PR.** Only\r\n  build-blocking fixes (max one extra commit). Everything else → follow-up PR.\r\n- **`.github\u002Fworkflows\u002Fspelling2.yml` always conflicts** and is always\r\n  \"take upstream wholesale\". The Tier-0 list in\r\n  [`references\u002F03-known-conflicts.md`](.\u002Freferences\u002F03-known-conflicts.md)\r\n  handles it — extend the list when you find the next file with this pattern.\r\n- **`gh pr create` on Windows can fail with \"Head sha can't be blank\"**\r\n  on freshly-pushed branches. The step-8 recipe wraps it in a 3× retry.\r\n  Do not \"fix\" it to use `--head \u003Cowner>:\u003Cbranch>` (that points `gh` at a fork).\r\n- **Cherry-pick over `git revert`-style commits is intentional, not\r\n  skipped.** We only skip revert-pairs where **both** sides are inside\r\n  the pending range. A revert of an already-merged commit must land —\r\n  otherwise the fork diverges silently.\r\n- **Single-host scheduler.** The stuck-lock is a read-then-check gate,\r\n  not an atomic lease. Run from ONE host. For multi-host fan-out, layer\r\n  atomic locking on top (GitHub Actions `concurrency: upstream-sync` is\r\n  easiest).\r\n- **CRLF\u002FLF on manifest files.** Cherry-picks preserve upstream endings,\r\n  but Tier-2 LLM-touched resolutions on `.yml`\u002F`.xml`\u002F`.csproj`\u002Fwinget\r\n  manifests may downgrade to LF. Re-normalize before staging — see\r\n  [`references\u002F03-conflict-triage.md`](.\u002Freferences\u002F03-conflict-triage.md#line-endings).\r\n- **PGO pin follows upstream.** `build\u002Fpgo\u002FTerminal.PGO.props` hard-pins the\r\n  PGO database to upstream's Windows Terminal `Major.Minor` (our `custom.props`\r\n  stays `0.1`, so it can't be derived). When a sync bumps the upstream version,\r\n  re-pin those two values or the build fails with `Could not find matching PGO\r\n  package`. Step 7's pre-build check covers this.\r\n\r\n## Troubleshooting\r\n\r\n| Issue | Solution |\r\n|---|---|\r\n| `02-compute-pending.ps1` throws \"No 'cherry picked from commit' trailer …\" | Fork has never used `cherry-pick -x` yet. Run the one-time [First-time sync](.\u002Freferences\u002Frecovery-procedures.md#first-time-sync-seeding-the-watermark). |\r\n| Stuck issue prevents new run | Resolve on the stuck branch, open + merge a PR (keep the trailer, don't squash), then **close the stuck issue**. The next scheduler tick proceeds. |\r\n| `03-cherry-pick-one.ps1` returns `\"skipped-empty\"` | Expected for upstream no-op commits and fork-already-applied patches. The loop skips and continues. |\r\n| Same file conflicts every run | Add it to [`references\u002F03-known-conflicts.md`](.\u002Freferences\u002F03-known-conflicts.md) with the right strategy (`take-upstream` or `take-ours`; `union` is reserved and currently escalates instead of auto-resolving). |\r\n| `gh pr create` returns \"Head sha can't be blank\" | Step 8 retries 3×. On slow networks, the operator may need a manual second run. |\r\n\r\n## References\r\n\r\n- [`references\u002Frun-a-sync.md`](.\u002Freferences\u002Frun-a-sync.md) — full eight-step procedure with commands.\r\n- [`references\u002F03-conflict-triage.md`](.\u002Freferences\u002F03-conflict-triage.md) — Tier 0\u002F1\u002F2\u002F3 conflict-resolution rubric.\r\n- [`references\u002F03-known-conflicts.md`](.\u002Freferences\u002F03-known-conflicts.md) — files with fixed Tier-0 resolutions.\r\n- [`references\u002Ffollow-up-pr.md`](.\u002Freferences\u002Ffollow-up-pr.md) — fix-in-PR vs. follow-up PR rubric and worktree workflow.\r\n- [`references\u002Frecovery-procedures.md`](.\u002Freferences\u002Frecovery-procedures.md) — direct-to-main, first-time seed, squash-merge recovery.\r\n- [`scripts\u002F02-compute-pending.ps1`](.\u002Fscripts\u002F02-compute-pending.ps1) — derive watermark + pending list (no state file).\r\n- [`scripts\u002F03-cherry-pick-one.ps1`](.\u002Fscripts\u002F03-cherry-pick-one.ps1) — cherry-pick one SHA with author\u002Fdate pinning + Tier-0\u002FTier-1.\r\n- [`scripts\u002F04-try-build.ps1`](.\u002Fscripts\u002F04-try-build.ps1) — run `bz no_clean`; log to `Generated Files\u002F...`.\r\n",{"name":5,"license":15,"description":7},"main","b83c3d762f8727f2ad299ddcc62fcf13bc7f35c7",".github\u002Fskills\u002Fupstream-sync",175,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fintelligent-terminal","https:\u002F\u002Fdevblogs.microsoft.com\u002Fcommandline\u002Fannouncing-intelligent-terminal-version-0-1\u002F","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-11 18:29:36",{"source":8,"skillName":5,"commands":63,"prompt":73,"zipAvailable":74},[64,67,70],{"tool":65,"command":66},"npx","npx skills add microsoft\u002Fintelligent-terminal --skill upstream-sync",{"tool":68,"command":69},"bunx","bunx skills add microsoft\u002Fintelligent-terminal --skill upstream-sync",{"tool":71,"command":72},"pnpm","pnpm dlx skills add microsoft\u002Fintelligent-terminal --skill upstream-sync","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fintelligent-terminal\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fupstream-sync\u002FSKILL.md",true,[76,82,86,90,94,98,102,108,112],{"path":77,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":80,"sourceHtmlUrl":81},"references\u002F03-conflict-triage.md","REFERENCE","参考文档",7886,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fintelligent-terminal\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fupstream-sync\u002Freferences\u002F03-conflict-triage.md",{"path":83,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":84,"sourceHtmlUrl":85},"references\u002F03-known-conflicts.md",2049,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fintelligent-terminal\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fupstream-sync\u002Freferences\u002F03-known-conflicts.md",{"path":87,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":88,"sourceHtmlUrl":89},"references\u002Ffollow-up-pr.md",6694,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fintelligent-terminal\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fupstream-sync\u002Freferences\u002Ffollow-up-pr.md",{"path":91,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":92,"sourceHtmlUrl":93},"references\u002Fmulti-node.md",13526,"https:\u002F\u002Fgithub.com\u002Fdavila7\u002Fclaude-code-templates\u002Fblob\u002Fmain\u002Fcli-tool\u002Fcomponents\u002Fskills\u002Fai-research\u002Fdistributed-training-ray-train\u002Freferences\u002Fmulti-node.md",{"path":95,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":96,"sourceHtmlUrl":97},"references\u002Frecovery-procedures.md",3013,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fintelligent-terminal\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fupstream-sync\u002Freferences\u002Frecovery-procedures.md",{"path":99,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":100,"sourceHtmlUrl":101},"references\u002Frun-a-sync.md",15587,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fintelligent-terminal\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fupstream-sync\u002Freferences\u002Frun-a-sync.md",{"path":103,"resourceType":104,"resourceTypeDesc":105,"sizeBytes":106,"sourceHtmlUrl":107},"scripts\u002F02-compute-pending.ps1","SCRIPT","脚本",8919,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fintelligent-terminal\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fupstream-sync\u002Fscripts\u002F02-compute-pending.ps1",{"path":109,"resourceType":104,"resourceTypeDesc":105,"sizeBytes":110,"sourceHtmlUrl":111},"scripts\u002F03-cherry-pick-one.ps1",12542,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fintelligent-terminal\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fupstream-sync\u002Fscripts\u002F03-cherry-pick-one.ps1",{"path":113,"resourceType":104,"resourceTypeDesc":105,"sizeBytes":114,"sourceHtmlUrl":115},"scripts\u002F04-try-build.ps1",7925,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fintelligent-terminal\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fupstream-sync\u002Fscripts\u002F04-try-build.ps1",[117,149,171,204,231,253],{"skillNo":118,"name":119,"nameZh":6,"description":120,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":121,"licenseFileUrl":122,"sourceHtmlUrl":123,"categories":124,"keywords":129,"publishedAt":47},"01M69BS17H119AHC0VA6CGCG80","store-listing-localizer","Automate Microsoft Store (Partner Center) listing localization for Intelligent Terminal (Store ID 9NMQC2SSJX24). Use when asked to export\u002Fimport Store listings, localize release notes \u002F descriptions \u002F captions \u002F features into 80+ languages, update listingData CSV, or push Store listing translations without manually clicking through Partner Center. Drives Partner Center export\u002Fimport via the Playwright MCP and merges per-locale translations into the listingData CSV.","Apache-2.0","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fintelligent-terminal\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fstore-listing-localizer\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fintelligent-terminal\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fstore-listing-localizer\u002FSKILL.md",[125,128],{"categoryNo":126,"categoryName":127,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000004","电子表格",{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[130,131,132,133,134,38,9,135,136,137,138,139,140,29,141,142,143,144,145,146,147,148],"store listing localizer","listing","store","notes","playwright","update","release","release notes","MCP","Captions","localize","features","playwright mcp","listings","export","localization","locale","automate","import",{"skillNo":150,"name":151,"nameZh":6,"description":152,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":153,"categories":154,"keywords":155,"publishedAt":47},"01M69BRY6Z1T250VCQDTQ8ZFMQ","release-notes","Generate user-facing release notes for Intelligent Terminal. Use when asked to write release notes, changelog, what-is-new summary, or prepare a release. Compares git commits between releases, looks up PR-linked issues and community contributors, then outputs formatted notes with \"Verbed + Impact + Scenario\" style bullets, issue references, and contributor thanks.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fintelligent-terminal\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Frelease-notes\u002FSKILL.md",[],[133,136,137,156,157,38,158,159,160,37,161,28,162,163,29,164,165,166,167,168,169,170],"pr","generate","git","prepare","community","issues","impact","contributor","references","changelog","releases","write","scenario","issue","contributors",{"skillNo":172,"name":173,"nameZh":6,"description":174,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":175,"categories":176,"keywords":184,"publishedAt":47},"01M69BRV95KH26NCNHGKX4BGTJ","pr-integration-test","Design, implement, and validate Intelligent Terminal integration tests for a target pull request or regression. Use when asked to add PR integration tests, convert a bug fix into E2E coverage, prove existing behavior still works, map tests to the release checklist, or verify E2E reports mark checklist cases complete.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fintelligent-terminal\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fpr-integration-test\u002FSKILL.md",[177,180,183],{"categoryNo":178,"categoryName":179,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":181,"categoryName":182,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[185,156,186,187,188,189,190,38,136,191,192,193,194,195,196,197,198,29,199,200,201,202,203],"test","pr integration test","integration test","integration","integration tests","pull request","validate","design","implement","coverage","regression","release checklist","fix","map","reports","request","bug","add","pull",{"skillNo":205,"name":206,"nameZh":6,"description":207,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":208,"categories":209,"keywords":211,"publishedAt":47},"01M69BRR7XQK0K0S4Z2Y81GX20","pr-accessibility","Review and repair native Windows WinUI, XAML, C++, UI Automation, keyboard, focus, screen-reader, high-contrast, scaling, settings, tab, pane, and agent-card accessibility changes. Use for accessibility analysis of Intelligent Terminal UI pull requests and focused local accessibility checks.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fintelligent-terminal\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fpr-accessibility\u002FSKILL.md",[210],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[156,212,213,214,215,216,217,38,218,219,220,221,222,223,224,225,226,227,228,229,203,230],"accessibility","pr accessibility","xaml","windows","pull requests","winui","automation","review","scaling","card","local","analysis","keyboard","focus","native","screen","contrast","ui","repair",{"skillNo":232,"name":233,"nameZh":6,"description":234,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":235,"categories":236,"keywords":237,"publishedAt":47},"01M69BRNTFHGZ2CND9G3KWHPS7","performance-review","Review Intelligent Terminal performance changes in local work, commit ranges, branches, or PRs. Use for renderer, text-buffer, VT, UI-thread, tab\u002Fpane, WTA, async, session, logging, allocation, event-amplification, benchmark, profiling, responsiveness, memory, and CI-cost changes.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fintelligent-terminal\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fperformance-review\u002FSKILL.md",[],[238,239,219,240,38,241,45,242,222,243,244,245,246,247,229,248,249,250,251,252],"performance","performance review","memory","benchmark","ci","branches","buffer","text","work","allocation","logging","for","event","renderer","async",{"skillNo":254,"name":255,"nameZh":6,"description":256,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":257,"categories":258,"keywords":260,"publishedAt":47},"01M69BRJ5CFMPN7NBQR9FVA17E","ghaw-pr-security","Review Intelligent Terminal pull requests for C++\u002FWinRT, COM, WTA, ACP, session MCP, hooks, terminal mutation, path, diagnostic, packaging, and GitHub Actions security regressions. Use for evidence-based immutable-diff review and structured HIGH\u002Fmedium\u002Flow findings.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fintelligent-terminal\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fghaw-pr-security\u002FSKILL.md",[259],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[156,261,262,216,263,38,264,138,219,265,266,267,268,269,270,203,271,272,273,249,274,275],"security","ghaw pr security","github","acp","packaging","actions","hooks","github actions","mutation","path","evidence","c++","diff","session","diff review"]