ci: refine plan orchestration and Windows payload routing (#7223)

* docs(ci): define test set orchestration

* docs(ci): make orchestration guidance incremental

* ci: separate merge policy from validation

* ci: narrow Windows payload validation

* docs(ci): restructure orchestration methodology

* docs(ci): treat mapping shape as architecture feedback

Author: PerishCode

.github/config/scopes.json

@@ -5,6 +5,7 @@
     "web_tests_required",
     "tools_dev_tests_required",
     "tools_pack_tests_required",
+    "windows_tools_pack_payload_tests_required",
     "ui_critical_validation_required",
     "ui_p0_validation_required",
     "visual_validation_required",
@@ -44,6 +45,29 @@
         "tools/pack/src/", "tools/pack/tests/", "tools/pack/resources/"
       ]
     },
+    "windows-launcher-payload": {
+      "prefixes": [
+        "tools/pack/src/win/", "tools/pack/resources/win/",
+        "packages/launcher-proto/src/", "packages/sidecar-proto/src/"
+      ],
+      "exact": [
+        "tools/pack/src/cache.ts",
+        "tools/pack/src/config.ts",
+        "tools/pack/src/launcher-layout.ts",
+        "tools/pack/src/launcher-runtime-snapshot.ts",
+        "tools/pack/src/lock.ts",
+        "tools/pack/src/resources.ts",
+        "tools/pack/src/update-cache-lifecycle-snapshot.ts",
+        "tools/pack/src/versions.ts",
+        "tools/pack/src/win-prebundle.ts",
+        "tools/pack/tests/launcher-payload-windows.test.ts",
+        "packages/platform/src/command.ts",
+        "packages/platform/src/index.ts",
+        "packages/release/src/index.ts",
+        "packages/sidecar/src/index.ts",
+        "packages/sidecar/src/paths.ts"
+      ]
+    },
     "daemon-core": {
       "prefixes": ["apps/daemon/src/", "apps/daemon/tests/"],
       "exact": ["docs/agent-adapters.md"],
@@ -118,6 +142,12 @@
       "effects": ["tools_dev_tests_required", "tools_pack_tests_required", "workspace_validation_required"],
       "confidence": "certain"
     },
+    {
+      "id": "certain-windows-launcher-payload",
+      "match": { "include": ["match://windows-launcher-payload"] },
+      "effects": ["windows_tools_pack_payload_tests_required"],
+      "confidence": "certain"
+    },
     {
       "id": "tools-pack-sources",
       "match": {
@@ -132,7 +162,7 @@
         "exact": ["package.json", "pnpm-lock.yaml", "pnpm-workspace.yaml", ".github/workflows/ci.yml", "e2e/package.json"],
         "regexes": ["^apps/[^/]+/package\\.json$", "^packages/[^/]+/package\\.json$", "^tools/[^/]+/package\\.json$"]
       },
-      "effects": ["daemon_tests_required", "web_tests_required", "tools_dev_tests_required", "tools_pack_tests_required"],
+      "effects": ["daemon_tests_required", "web_tests_required", "tools_dev_tests_required", "tools_pack_tests_required", "windows_tools_pack_payload_tests_required"],
       "confidence": "medium"
     },
     {

.github/scripts/scopes.py

@@ -189,7 +189,7 @@ def enabled_workloads(outputs, ci_mode, full_lanes):
         "preflight": True,
         "workspace_unit_tests": broad,
         "daemon_unit_tests": outputs["daemon_tests_required"],
-        "windows_tools_pack_payload_tests": full_lanes or outputs["tools_pack_tests_required"],
+        "windows_tools_pack_payload_tests": full_lanes or outputs["windows_tools_pack_payload_tests_required"],
         "web_workspace_tests": full_lanes or outputs["web_tests_required"],
         "e2e_vitest": full_lanes or outputs["web_tests_required"] or outputs["ui_p0_validation_required"],
         "playwright_critical": outputs["ui_critical_validation_required"] and not ui_p0,

.github/workflows/ci.yml

@@ -384,7 +384,7 @@ jobs:
           runner-labels: ${{ toJSON(fromJSON(needs.runners.outputs.runs_on).windows_tools) }}
 
       - name: Windows launcher payload archive tests
-        run: pnpm --filter @open-design/tools-pack exec vitest run tests/launcher-payload.test.ts
+        run: pnpm --filter @open-design/tools-pack exec vitest run tests/launcher-payload-windows.test.ts
 
   web_workspace_tests:
     name: Web workspace tests (${{ matrix.shard }}/2)
@@ -661,69 +661,26 @@ jobs:
         if: ${{ steps.visual.outcome != 'success' }}
         run: exit 1
 
-  validate:
-    name: Validate workspace
-    needs:
-      - plan
-      - runners
-      - static_gate
-      - preflight
-      - workspace_unit_tests
-      - daemon_unit_tests
-      - windows_tools_pack_payload_tests
-      - web_workspace_tests
-      - e2e_vitest
-      - playwright_critical
-      - ui_p0
-      - playwright_visual
-    if: ${{ always() }}
+  # This policy is a sibling of the validation workloads, not their prerequisite.
+  # Labeled merge groups still receive the same workload coverage before the
+  # required Validate workspace check rejects the converged result.
+  merge_policy:
+    name: Merge policy
+    needs: [plan, runners]
+    if: ${{ github.event_name == 'merge_group' }}
     runs-on: ${{ fromJSON(needs.runners.outputs.runs_on).control }}
     timeout-minutes: 5
 
     steps:
-      # The merge-blocking label gate below produces a `handoff/comment` artifact when it ejects a
+      # The merge-blocking label gate produces a `handoff/comment` artifact when it ejects a
       # queued PR, and that production goes through `.github/scripts/handoff.py` (the only
-      # sanctioned source of handoff names and layout). Only the merge_group context can eject,
-      # so pull_request runs skip the checkout entirely.
+      # sanctioned source of handoff names and layout).
       - name: Checkout handoff helper
-        if: ${{ github.event_name == 'merge_group' }}
         uses: actions/checkout@v6.0.2
         with:
           sparse-checkout: .github
           sparse-checkout-cone-mode: true
 
-      - name: Check workspace validation jobs
-        env:
-          NEEDS_JSON: ${{ toJSON(needs) }}
-        run: |
-          set -euo pipefail
-          echo "$NEEDS_JSON" | jq .
-          failures="$(echo "$NEEDS_JSON" | jq -r '
-            to_entries[]
-            | select(.value.result != "success" and .value.result != "skipped")
-            | "\(.key)=\(.value.result)"')"
-          if [ -n "$failures" ]; then
-            echo "Workspace validation failed:"
-            echo "$failures"
-            exit 1
-          fi
-
-          required_misses="$(echo "$NEEDS_JSON" | jq -r '
-            . as $needs |
-            (($needs.plan.outputs.run // "{}") | fromjson) as $run |
-            (
-              ["plan"]
-              + [$run | to_entries[] | select(.value) | .key]
-            )[]
-            | select(($needs[.].result // "missing") != "success")
-            | "\(.)=\($needs[.].result // "missing")"
-          ')"
-          if [ -n "$required_misses" ]; then
-            echo "Required validation jobs did not succeed:"
-            echo "$required_misses"
-            exit 1
-          fi
-
       - name: Block merge while a merge-blocking label is present
         id: merge_blocking_label_gate
         # Hard gate: a PR that still carries `needs-validation` or `needs-maintainer-check` must
@@ -895,6 +852,59 @@ jobs:
           name: ${{ steps.merge_blocking_label_gate.outputs.comment_name }}
           path: ${{ steps.merge_blocking_label_gate.outputs.comment_path }}
 
+  validate:
+    name: Validate workspace
+    needs:
+      - plan
+      - runners
+      - merge_policy
+      - static_gate
+      - preflight
+      - workspace_unit_tests
+      - daemon_unit_tests
+      - windows_tools_pack_payload_tests
+      - web_workspace_tests
+      - e2e_vitest
+      - playwright_critical
+      - ui_p0
+      - playwright_visual
+    if: ${{ always() }}
+    runs-on: ${{ fromJSON(needs.runners.outputs.runs_on).control }}
+    timeout-minutes: 5
+
+    steps:
+      - name: Check workspace validation jobs
+        env:
+          NEEDS_JSON: ${{ toJSON(needs) }}
+        run: |
+          set -euo pipefail
+          echo "$NEEDS_JSON" | jq .
+          failures="$(echo "$NEEDS_JSON" | jq -r '
+            to_entries[]
+            | select(.value.result != "success" and .value.result != "skipped")
+            | "\(.key)=\(.value.result)"')"
+          if [ -n "$failures" ]; then
+            echo "Workspace validation failed:"
+            echo "$failures"
+            exit 1
+          fi
+
+          required_misses="$(echo "$NEEDS_JSON" | jq -r '
+            . as $needs |
+            (($needs.plan.outputs.run // "{}") | fromjson) as $run |
+            (
+              ["plan"]
+              + [$run | to_entries[] | select(.value) | .key]
+            )[]
+            | select(($needs[.].result // "missing") != "success")
+            | "\(.)=\($needs[.].result // "missing")"
+          ')"
+          if [ -n "$required_misses" ]; then
+            echo "Required validation jobs did not succeed:"
+            echo "$required_misses"
+            exit 1
+          fi
+
       - name: Download pending hash map
         uses: actions/download-artifact@v8
         continue-on-error: true

AGENTS.md

@@ -8,7 +8,7 @@ This file is the single source of truth for agents entering this repository. Rea
 - Contribution and environment: `CONTRIBUTING.md`, `docs/i18n/CONTRIBUTING.zh-CN.md`.
 - Architecture and protocols: `docs/architecture.md`, `docs/skills-protocol.md`, `docs/agent-adapters.md`, `docs/modes.md`.
 - Historical product baseline: `docs/spec.md`, `docs/roadmap.md` (both explicitly archived; do not treat their dated decisions as current behavior).
-- References and current plans: `docs/references.md`, `docs/code-review-guidelines.md`, `specs/current/maintainability-roadmap.md`, `specs/current/ci.md` (CI scope confidence methodology — required before changing confidence or guard fields in `scripts/scopes.ts`).
+- References and current plans: `docs/references.md`, `docs/code-review-guidelines.md`, `specs/current/maintainability-roadmap.md`, `specs/current/ci.md` (CI scope confidence methodology — required before changing planner confidence, routing, or omission policy in `.github/config/scopes.json` and `.github/scripts/scopes.py`).
 - Directory-level agent guidance: `.github/AGENTS.md`, `apps/AGENTS.md`, `packages/AGENTS.md`, `tools/AGENTS.md`, `e2e/AGENTS.md`.
 - Packaged auto-update architecture and high-confidence local harness: read `tools/pack/AGENTS.md` section "Packaged auto-update architecture and harness" before touching packaged updater code, release-channel identity, installer behavior, or updater UI.
 - Packaged build cache contract: `tools/pack/CACHE.md` (determinant rules, materialization-time parameters, confidence grading — required before changing any build-cache node key).
@@ -151,6 +151,67 @@ CI-related GitHub automation uses a two-layer architecture:
 
 Do not add a new business-named follow-on workflow such as `foo.comment.atom.yml` or `bar.autofix.atom.yml` without first trying to express the flow as a `ci.yml` producer plus the existing `comment`, `autofix`, or `report` capability. Keep artifact naming, storage layout, and parser behavior centralized in `.github/scripts/handoff.py`; do not let individual workflows invent parallel handoff conventions.
 
+## CI test-set orchestration guidance
+
+Use the following as a recommended convergence model, not a repository-wide
+conformance gate. Existing workflows and coarse test lanes may remain while
+their boundaries are understood. Do not block an unrelated change or require it
+to repay adjacent orchestration debt solely because it touches an existing
+lane. Apply these recommendations incrementally when the local scope and
+measured scheduling benefit justify the migration.
+
+Prefer one selection direction: changed paths → source units → test sets →
+execution workloads. Because the `plan` job runs before and governs downstream
+jobs, new omission policy should live in the planner rather than rely on a
+downstream guard to justify it after scheduling has already occurred.
+
+When a CI area is being reorganized, prefer three named responsibilities:
+
+- **Source units** name stable ownership or behavior boundaries in production,
+  test, fixture, and control-plane paths. Prefer composing repeated selectors
+  under a named unit instead of copying prefixes into unrelated rules.
+- **Test sets** name independently useful semantic validation groups. Their
+  membership and execution contract should converge on one authoritative
+  declaration instead of accumulating more matrix or file-list copies across
+  planner configuration, workflow YAML, and framework-local registries.
+- **Routes** map source units to the test sets required to validate them. Routes
+  should express impact rather than runner mechanics; runner image, setup,
+  sharding, and job packing can remain execution concerns derived after
+  selection.
+
+Good split candidates have a stable boundary, change work that can actually be
+omitted, and carry enough runtime cost or diagnostic value to justify another
+scheduling identity. Directory size, file count, or the ability to write a
+narrower glob is weak evidence on its own. Prefer a small number of composable
+semantic units over per-file mappings, exception lists, or negative-rule
+forests. Treat existing duplicated or implicit declarations as migration
+surfaces without requiring every nearby change to remove them.
+
+Before promoting a new route from observation to active omission, retain
+conservative behavior such as:
+
+- unknown, mixed, unresolved, invalid, or below-threshold input selects the
+  conservative full plan;
+- editing a test, fixture, or suite manifest selects the test set that consumes
+  it; shared harness, contract, setup, or lockfile changes fan out to every
+  affected set;
+- making a selected test-set identifier that the executor cannot run fail
+  visibly instead of being ignored;
+- direct planner tests cover representative in-bound, out-of-bound, mixed, and
+  fallback inputs without reimplementing the evaluator in another language.
+
+Keep scope routing and hash invalidation conceptually orthogonal: scope answers
+which test sets are necessary for a change, while hash answers whether the
+selected workload's declared inputs equal a previous invocation. New designs
+should not use hash equality to weaken source-to-test coverage or copy route
+policy into `.github/config/hash.json`.
+
+For work whose purpose is CI orchestration, start by inventorying the current
+chain from changed path to match, effect, workload, job command, and concrete
+test cases. Prefer naming or removing implicit joins before making them finer.
+Changes under `.github/` must also follow `.github/AGENTS.md` and the current
+confidence methodology in `specs/current/ci.md`.
+
 ## Release channel model
 
 - `beta` is the daily R&D/development validation channel. It is optimized for fast development feedback and is not part of the stable promotion gate.