Fix release-line Skia sync state preservation (#4660)

[skia-sync] Preserve release-line sync state (#4660)

Context: https://github.com/mono/SkiaSharp/actions/runs/30937099860
Context: https://github.com/mono/SkiaSharp/actions/runs/30942491593
Validation: https://github.com/mono/SkiaSharp/actions/runs/30956446553

Release-line syncs replaced the triggering revision's current
update-skia skill with stale servicing-branch helpers. This downgraded
versions such as 4.150.2 to 4.150.0 and left initialized submodules at
SHAs from the previous parent checkout.

Stage the complete update-skia skill outside the mutable product
checkout and prepare branches deterministically from the resolved
parent and Skia SHAs. Recursively align every submodule before creating
the mutable mono/skia branch.

Hydrate Skia dependencies before version reconciliation. Preserve
servicing and semantic versions unless the corresponding DEPS identity
changes, while permitting source-backed provenance backfills.

Generated mono/skia PRs now require merge commits so upstream ancestry
remains available to future sync detection. The final m150 validation
preserved 4.150.2, built from source, and passed the full test suite.

Co-authored-by: Matthew Leibowitz <mattleibow@live.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: mattleibow

.agents/skills/update-skia/SKILL.md

@@ -78,9 +78,9 @@ An update is complete only when:
   have a matching final decision, exact-SHA evidence, and reconciled Component Governance metadata.
   A dependency recorded as preserved must still equal the fork-base revision.
 - Let `update_versions.py` identify dependency changes from exact base/final DEPS. For every tracked
-  changed dependency, derive the semantic version from checked-out source and complete the
-  `skia_dependency` verification fields before the helper can pass. Never update an unrelated
-  manifest version when its DEPS identity did not change.
+  changed dependency, and every legacy tracked registration missing verification evidence, derive
+  the semantic version from checked-out source and complete the `skia_dependency` fields before the
+  helper can pass. Never update a manifest version when its DEPS identity did not change.
 - Components not sourced from Skia DEPS, including ANGLE and its dependencies, are updated in
   separate dependency PRs rather than bundled into a Skia upstream sync.
 - Never use `externals-download` after a submodule/native/C API change.
@@ -128,6 +128,9 @@ needed for that phase.
 
 ## Deterministic helpers
 
+- Automation stages this entire skill outside the mutable product checkout and exports its path as
+  `SKIA_SYNC_SKILL_DIR`. After changing the product branch, continue reading phase references and
+  running helpers from that staged directory rather than the branch-local `.agents` tree.
 - `scripts/update_versions.py` updates and validates version surfaces, Skia hashes, and deterministic
   DEPS-to-Component-Governance identity/review signals.
 - `scripts/regenerate_bindings.py` runs every binding configuration, restores HarfBuzz,

.agents/skills/update-skia/references/phases/04-05-branch-and-merge.md

@@ -5,31 +5,27 @@ Read only `DEPS: Fork-Customized Dependencies`, `Genuine Merge Required`,
 `Conflict Resolution by File Category`, and `Verify-Upstream-or-Reapply` in
 [../known-gotchas.md](../known-gotchas.md).
 
-## Phase 04 — branch from the resolved bases
+## Phase 04 — create matched feature branches
 
-Create or verify the parent feature branch:
+Use the deterministic branch helper for a new update. It consumes the exact parent and Skia SHAs
+resolved in Phase 01; do not replace them with current branch tips or reproduce its Git operations
+manually.
 
 ```bash
-git fetch origin "{BASE_BRANCH}"
-git checkout -b "{HEAD_BRANCH}" "origin/{BASE_BRANCH}"
+python3 "${SKIA_SYNC_SKILL_DIR:-.agents/skills/update-skia}/scripts/prepare_branches.py" \
+  --repo-root "${GITHUB_WORKSPACE:-$PWD}"
 ```
 
-Create or verify the mono/skia feature branch at the exact submodule pointer recorded by the
-parent base:
+The helper fails instead of resetting existing branches or dirty files. On success:
 
-```bash
-BASE_SUB_SHA=$(git ls-tree "origin/{BASE_BRANCH}" -- externals/skia | awk '{print $3}')
-export SKIA_SYNC_SKIA_BASE_SHA="$BASE_SUB_SHA"
-git -C externals/skia fetch origin "{SKIA_BASE_BRANCH}"
-git -C externals/skia checkout "$BASE_SUB_SHA"
-git -C externals/skia branch -r --contains "$BASE_SUB_SHA" |
-  grep "origin/{SKIA_BASE_BRANCH}"
-git -C externals/skia checkout -b "{HEAD_BRANCH}"
-```
+- the parent feature branch starts at `{PARENT_BASE_SHA}`;
+- every recursive submodule matches that parent commit;
+- the mono/skia pointer is verified against `{SKIA_BASE_SHA}` and
+  `origin/{SKIA_BASE_BRANCH}`; and
+- the mono/skia feature branch is created from that exact pointer.
 
-If a branch already exists, inspect its base and commits before continuing. Reuse only the
-intended update branch; never reset or overwrite unrelated work. Automation may start with the
-submodule already aligned, but must still verify the pointer and bases.
+If either feature branch already exists, stop and inspect its base and commits. Reuse it only when
+it is the intended continuation; never reset or overwrite unrelated work.
 
 ## Phase 05 — genuine upstream merge
 
@@ -117,7 +113,7 @@ fork patch. Return to the parent repository root and generate the diff-of-diffs
 merge:
 
 ```bash
-python3 .agents/skills/update-skia/scripts/audit_fork_patches.py \
+python3 "${SKIA_SYNC_SKILL_DIR:-.agents/skills/update-skia}/scripts/audit_fork_patches.py" \
   --old-upstream "$SKIA_SYNC_BASE_UPSTREAM_SHA" \
   --new-upstream "$SKIA_SYNC_TARGET_UPSTREAM_SHA" \
   --fork-base "$SKIA_SYNC_SKIA_BASE_SHA" \

.agents/skills/update-skia/references/phases/06-07-update-and-build.md

@@ -2,10 +2,19 @@
 
 ## Phase 06 — update version surfaces
 
-From the parent repository, run the maintained helper:
+Hydrate the dependencies recorded by the merged Skia `DEPS` before inspecting their
+semantic-version evidence:
 
 ```bash
-python3 .agents/skills/update-skia/scripts/update_versions.py
+python3 externals/skia/tools/git-sync-deps
+```
+
+This synchronizes dependency source only; it does not build native binaries. Then run the
+maintained version helper from the parent repository:
+
+```bash
+python3 "${SKIA_SYNC_SKILL_DIR:-.agents/skills/update-skia}/scripts/update_versions.py" \
+  --repo-root "${GITHUB_WORKSPACE:-$PWD}"
 ```
 
 The helper updates and validates `scripts/VERSIONS.txt`, the Skia registrations in
@@ -34,8 +43,9 @@ A revision-only roll may retain the same semantic version, but still requires th
 identity and source evidence. The helper rejects a manifest version bump when that dependency's
 DEPS identity did not change. It is idempotent; rerun it after every final DEPS/native adaptation
 and after the final mono/skia fix commit so the parent records the exact tested state.
-Every tracked registration, including an unchanged baseline entry, must retain non-empty
-`version_source` evidence.
+Every tracked registration, including an unchanged legacy entry, must have non-empty
+`version_source` evidence. Backfill missing `skia_dependency` evidence from the hydrated source so
+supported branches become compliant over time without changing semantic versions unnecessarily.
 The script proves coverage and consistency; the independent review must re-read each cited source
 to validate the agent's semantic-version claim.
 
@@ -96,7 +106,8 @@ explanatory commit.
 
 After every mono/skia adaptation, rerun `audit_fork_patches.py` with the Phase 05 arguments. Fill
 new or changed rows and require `--validate` to pass again. Reuse the exact Phase 05
-`python3 .agents/skills/update-skia/scripts/audit_fork_patches.py` command rather than searching
+`python3 "${SKIA_SYNC_SKILL_DIR:-.agents/skills/update-skia}/scripts/audit_fork_patches.py"`
+command rather than searching
 for another copy of the helper.
 
 Before Phase 08, rerun `update_versions.py` against final `DEPS`, then reconcile every row in

.agents/skills/update-skia/references/phases/08-10-bindings-and-tests.md

@@ -5,7 +5,8 @@
 The native build must run first so dependency headers exist:
 
 ```bash
-python3 .agents/skills/update-skia/scripts/regenerate_bindings.py
+python3 "${SKIA_SYNC_SKILL_DIR:-.agents/skills/update-skia}/scripts/regenerate_bindings.py" \
+  --repo-root "${GITHUB_WORKSPACE:-$PWD}"
 dotnet build binding/SkiaSharp/SkiaSharp.csproj
 ```
 
@@ -119,15 +120,16 @@ mono/skia tree before moving to Phase 11:
 2. From the parent root, run the metadata finalizer:
 
    ```bash
-   python3 .agents/skills/update-skia/scripts/update_versions.py
+   python3 "${SKIA_SYNC_SKILL_DIR:-.agents/skills/update-skia}/scripts/update_versions.py" \
+     --repo-root "${GITHUB_WORKSPACE:-$PWD}"
    ```
 
    If it fails, reconcile every `skia-dependency-changes.json` row with checked-out source,
    `cgmanifest.json`, and `skia-dependency-decisions.md`, then rerun until it passes.
 3. Refresh the fork audit against the **current final mono/skia HEAD**:
 
    ```bash
-   python3 .agents/skills/update-skia/scripts/audit_fork_patches.py \
+   python3 "${SKIA_SYNC_SKILL_DIR:-.agents/skills/update-skia}/scripts/audit_fork_patches.py" \
      --old-upstream "$SKIA_SYNC_BASE_UPSTREAM_SHA" \
      --new-upstream "$SKIA_SYNC_TARGET_UPSTREAM_SHA" \
      --fork-base "$SKIA_SYNC_SKIA_BASE_SHA" \

.agents/skills/update-skia/scripts/prepare_branches.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+
+"""Create matched SkiaSharp and mono/skia update branches from exact bases."""
+
+import argparse
+import os
+import subprocess
+from pathlib import Path
+
+
+class PreparationError(RuntimeError):
+    pass
+
+
+def git(repo: Path, *args: str, check: bool = True) -> subprocess.CompletedProcess[str]:
+    result = subprocess.run(
+        ["git", "-C", str(repo), *args],
+        capture_output=True,
+        text=True,
+    )
+    if check and result.returncode != 0:
+        detail = result.stderr.strip() or result.stdout.strip()
+        raise PreparationError(f"git {' '.join(args)} failed in {repo}: {detail}")
+    return result
+
+
+def git_output(repo: Path, *args: str) -> str:
+    return git(repo, *args).stdout.rstrip("\r\n")
+
+
+def branch_exists(repo: Path, branch: str) -> bool:
+    result = git(
+        repo,
+        "show-ref",
+        "--verify",
+        "--quiet",
+        f"refs/heads/{branch}",
+        check=False,
+    )
+    if result.returncode not in (0, 1):
+        raise PreparationError(f"Could not inspect branch {branch} in {repo}.")
+    return result.returncode == 0
+
+
+def require_clean(repo: Path, *, ignore_submodules: bool = False) -> None:
+    args = ["status", "--porcelain=v1", "--untracked-files=all"]
+    if ignore_submodules:
+        args.append("--ignore-submodules=all")
+    status = git_output(repo, *args)
+    if status:
+        raise PreparationError(f"Worktree is not clean: {repo}\n{status}")
+
+
+def require_ancestor(repo: Path, commit: str, remote_branch: str) -> None:
+    result = git(
+        repo,
+        "merge-base",
+        "--is-ancestor",
+        commit,
+        remote_branch,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise PreparationError(f"{commit} is not contained by {remote_branch}.")
+
+
+def prepare_branches(
+    repo_root: Path,
+    base_branch: str,
+    parent_base_sha: str,
+    skia_base_branch: str,
+    skia_base_sha: str,
+    head_branch: str,
+) -> None:
+    repo_root = repo_root.resolve()
+    skia_root = repo_root / "externals" / "skia"
+
+    git_output(repo_root, "rev-parse", "--show-toplevel")
+    git_output(skia_root, "rev-parse", "--show-toplevel")
+    git(repo_root, "check-ref-format", "--branch", head_branch)
+    git(skia_root, "check-ref-format", "--branch", head_branch)
+
+    require_clean(repo_root, ignore_submodules=True)
+    require_clean(skia_root)
+    if branch_exists(repo_root, head_branch):
+        raise PreparationError(f"Parent branch already exists: {head_branch}")
+    if branch_exists(skia_root, head_branch):
+        raise PreparationError(f"Skia branch already exists: {head_branch}")
+
+    git(
+        repo_root,
+        "fetch",
+        "--no-tags",
+        "origin",
+        f"+refs/heads/{base_branch}:refs/remotes/origin/{base_branch}",
+    )
+    git(
+        skia_root,
+        "fetch",
+        "--no-tags",
+        "origin",
+        f"+refs/heads/{skia_base_branch}:refs/remotes/origin/{skia_base_branch}",
+    )
+
+    parent_base_sha = git_output(
+        repo_root, "rev-parse", "--verify", f"{parent_base_sha}^{{commit}}"
+    )
+    skia_base_sha = git_output(
+        skia_root, "rev-parse", "--verify", f"{skia_base_sha}^{{commit}}"
+    )
+    require_ancestor(repo_root, parent_base_sha, f"origin/{base_branch}")
+    require_ancestor(skia_root, skia_base_sha, f"origin/{skia_base_branch}")
+
+    tree_entry = git_output(
+        repo_root, "ls-tree", parent_base_sha, "--", "externals/skia"
+    ).split()
+    if len(tree_entry) < 3 or tree_entry[1] != "commit":
+        raise PreparationError(
+            f"{parent_base_sha} does not contain the externals/skia submodule."
+        )
+    if tree_entry[2] != skia_base_sha:
+        raise PreparationError(
+            "Resolved Skia base does not match the parent gitlink: "
+            f"{skia_base_sha} != {tree_entry[2]}"
+        )
+
+    git(repo_root, "checkout", "-b", head_branch, parent_base_sha)
+    git(repo_root, "submodule", "sync", "--recursive")
+    git(repo_root, "submodule", "update", "--init", "--recursive")
+
+    submodule_status = git_output(
+        repo_root, "submodule", "status", "--recursive"
+    )
+    mismatches = [
+        line for line in submodule_status.splitlines() if line and line[0] in "-+U"
+    ]
+    if mismatches:
+        raise PreparationError(
+            "Submodules do not match the selected parent:\n" + "\n".join(mismatches)
+        )
+
+    actual_skia_sha = git_output(skia_root, "rev-parse", "HEAD")
+    if actual_skia_sha != skia_base_sha:
+        raise PreparationError(
+            f"Skia is at {actual_skia_sha}, expected {skia_base_sha}."
+        )
+
+    git(skia_root, "checkout", "-b", head_branch, skia_base_sha)
+    print(f"Created {head_branch} from parent {parent_base_sha}.")
+    print(f"Created externals/skia/{head_branch} from {skia_base_sha}.")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Create matched SkiaSharp and mono/skia update branches."
+    )
+    parser.add_argument(
+        "--repo-root",
+        type=Path,
+        default=Path(os.environ.get("GITHUB_WORKSPACE", ".")),
+    )
+    parser.add_argument("--base-branch", default=os.environ.get("SKIA_SYNC_BASE_BRANCH"))
+    parser.add_argument(
+        "--parent-base-sha", default=os.environ.get("SKIA_SYNC_PARENT_BASE_SHA")
+    )
+    parser.add_argument(
+        "--skia-base-branch", default=os.environ.get("SKIA_SYNC_SKIA_BASE_BRANCH")
+    )
+    parser.add_argument(
+        "--skia-base-sha", default=os.environ.get("SKIA_SYNC_SKIA_BASE_SHA")
+    )
+    parser.add_argument("--head-branch", default=os.environ.get("SKIA_SYNC_HEAD_BRANCH"))
+    args = parser.parse_args()
+
+    required = {
+        "--base-branch": args.base_branch,
+        "--parent-base-sha": args.parent_base_sha,
+        "--skia-base-branch": args.skia_base_branch,
+        "--skia-base-sha": args.skia_base_sha,
+        "--head-branch": args.head_branch,
+    }
+    missing = [name for name, value in required.items() if not value]
+    if missing:
+        parser.error("missing required values: " + ", ".join(missing))
+
+    try:
+        prepare_branches(
+            args.repo_root,
+            args.base_branch,
+            args.parent_base_sha,
+            args.skia_base_branch,
+            args.skia_base_sha,
+            args.head_branch,
+        )
+    except PreparationError as error:
+        parser.exit(1, f"error: {error}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())