diff --git a/.github/workflows/dotnet-port-api-nightly.lock.yml b/.github/workflows/dotnet-port-api-nightly.lock.yml index 2c9bc89e..ce769008 100644 --- a/.github/workflows/dotnet-port-api-nightly.lock.yml +++ b/.github/workflows/dotnet-port-api-nightly.lock.yml @@ -1,4 +1,4 @@ -# gh-aw-metadata: {"schema_version":"v4","frontmatter_hash":"f53a700d166f04f335b4ff433b8c0ade2ebe6bb868f0d72e2afca2e551f1ee17","body_hash":"bb36433b52028317df752526bd2498e041a4f302bf8d5e2a991124b4b52de5f9","compiler_version":"v0.83.4","strict":true,"agent_id":"copilot","agent_model":"gpt-5.4","engine_versions":{"copilot":"1.0.75"}} +# gh-aw-metadata: {"schema_version":"v4","frontmatter_hash":"f53a700d166f04f335b4ff433b8c0ade2ebe6bb868f0d72e2afca2e551f1ee17","body_hash":"0931961870f8720472906dd775ae585d8984a887a3819f3e13c73065fea0979f","compiler_version":"v0.83.4","strict":true,"agent_id":"copilot","agent_model":"gpt-5.4","engine_versions":{"copilot":"1.0.75"}} # gh-aw-manifest: {"version":1,"secrets":["COPILOT_GITHUB_TOKEN","GH_AW_CI_TRIGGER_TOKEN","GH_AW_GITHUB_MCP_SERVER_TOKEN","GH_AW_GITHUB_TOKEN","GITHUB_TOKEN"],"actions":[{"repo":"actions/cache/restore","sha":"55cc8345863c7cc4c66a329aec7e433d2d1c52a9","version":"v6.1.0"},{"repo":"actions/cache/save","sha":"55cc8345863c7cc4c66a329aec7e433d2d1c52a9","version":"v6.1.0"},{"repo":"actions/checkout","sha":"3d3c42e5aac5ba805825da76410c181273ba90b1","version":"v7.0.1"},{"repo":"actions/download-artifact","sha":"3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c","version":"v8.0.1"},{"repo":"actions/github-script","sha":"3a2844b7e9c422d3c10d287c895573f7108da1b3","version":"v9.0.0"},{"repo":"actions/setup-node","sha":"820762786026740c76f36085b0efc47a31fe5020","version":"v7.0.0"},{"repo":"actions/upload-artifact","sha":"043fb46d1a93c77aae656e7c1c64a875d1fc6a0a","version":"v7.0.1"},{"repo":"github/gh-aw-actions/setup","sha":"e89c65e17eb281bbd5ff2ff9e9199a03e96654c7","version":"v0.83.4"}],"containers":[{"image":"ghcr.io/github/gh-aw-firewall/agent:0.27.42","digest":"sha256:26a8af4e5566485b02f52af59ee03803ae798271a9619d4767e94d07806deb9b","pinned_image":"ghcr.io/github/gh-aw-firewall/agent:0.27.42@sha256:26a8af4e5566485b02f52af59ee03803ae798271a9619d4767e94d07806deb9b"},{"image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.27.42","digest":"sha256:944f2686c9ab9bec338fd14b662461662f77cd12cd0ea8a3e7cb8c0987cd1607","pinned_image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.27.42@sha256:944f2686c9ab9bec338fd14b662461662f77cd12cd0ea8a3e7cb8c0987cd1607"},{"image":"ghcr.io/github/gh-aw-firewall/squid:0.27.42","digest":"sha256:42dfeb649c680a8558cd5423dbc530b653a69413e35ffbe5e71da5d48c94bdf0","pinned_image":"ghcr.io/github/gh-aw-firewall/squid:0.27.42@sha256:42dfeb649c680a8558cd5423dbc530b653a69413e35ffbe5e71da5d48c94bdf0"},{"image":"ghcr.io/github/gh-aw-mcpg:v0.4.6","digest":"sha256:fecabec51bbc41f2ad61076d6bcd9a36ef23b142e672a444e054d37fc29de93c","pinned_image":"ghcr.io/github/gh-aw-mcpg:v0.4.6@sha256:fecabec51bbc41f2ad61076d6bcd9a36ef23b142e672a444e054d37fc29de93c"},{"image":"ghcr.io/github/gh-aw-node","digest":"sha256:a8082161d7dceda14b68f32eb39d0eaa96b825d07f5895b096afab9d9e0c7748","pinned_image":"ghcr.io/github/gh-aw-node@sha256:a8082161d7dceda14b68f32eb39d0eaa96b825d07f5895b096afab9d9e0c7748"},{"image":"ghcr.io/github/github-mcp-server:v1.7.0","digest":"sha256:c491ffdf6f4c85cb5397021bc655edb8ab825c6f5f568e7597d77a1bd7c4d308","pinned_image":"ghcr.io/github/github-mcp-server:v1.7.0@sha256:c491ffdf6f4c85cb5397021bc655edb8ab825c6f5f568e7597d77a1bd7c4d308"}]} # This file was automatically generated by gh-aw (v0.83.4). DO NOT EDIT. To debug this workflow, load the skill at https://github.com/github/gh-aw/blob/main/debug.md # diff --git a/.github/workflows/dotnet-port-api-nightly.md b/.github/workflows/dotnet-port-api-nightly.md index 19209ed0..6a3a01f3 100644 --- a/.github/workflows/dotnet-port-api-nightly.md +++ b/.github/workflows/dotnet-port-api-nightly.md @@ -62,7 +62,11 @@ You are a nightly porting agent for the Go SDK in `microsoft/agent-framework-go` Your job is to keep the Go SDK's public API and feature surface aligned with the upstream .NET Agent Framework implementation under `microsoft/agent-framework/dotnet`. -Litmus test: a change is in scope only if porting it adds or modifies an exported Go symbol (type, function, method, field, option, or interface) or introduces a new user-facing capability; otherwise defer to `[dotnet-port-fixes]`. +Classify the upstream change before designing its Go implementation. Classification follows the upstream contract, not whether Go could implement a subset without exported symbols: + +- **API/feature port:** Upstream adds or changes a public option, builder method, exported type or member, opt-in or experimental switch, or user-visible capability. It remains an API/feature port when motivated by a bug, linked to a bug issue, or implementable through unexported Go code. `[dotnet-port-api]` owns the complete change, including its tests. +- **Fix/test port:** Upstream corrects an existing capability under the existing public API, configuration, and defaults, or adds tests for such a correction, without introducing new enablement or user-visible capability. `[dotnet-port-fixes]` owns it only when the complete Go port also needs no exported-symbol change. +- If classification is uncertain, `[dotnet-port-fixes]` must defer, so treat the candidate as an API/feature port until maintainers decide otherwise. ## Workspace Layout @@ -87,7 +91,7 @@ Use `upstream-agent-framework/main` as the upstream reference. For example, insp Inspect recent upstream .NET commits and merged upstream PRs from a practical recent window. Use the commits themselves as the source of truth for choosing the inspection scope. -Before doing new work, check existing Go SDK issues and pull requests — both open and recently closed — created by the porting workflows with the `[dotnet-port-api]` or `[dotnet-port-fixes]` title prefix. These workflows run with read-only permissions and report results as tracking issues that link the proposed PR, so search issues (not only pull requests). If either workflow has already addressed the same upstream commit, the same .NET PR, or the same Go package or behavior — whether through an upstream port or a Go-misalignment fallback — do not duplicate it; select a different candidate or call `noop` with a concise explanation that links the existing issue or PR. When in doubt about whether a candidate belongs to this workflow or to `[dotnet-port-fixes]`, apply the litmus test above and defer rather than risk a duplicate. +Before doing new work, check existing Go SDK issues and pull requests — both open and recently closed — created by the porting workflows with the `[dotnet-port-api]` or `[dotnet-port-fixes]` title prefix. These workflows run with read-only permissions and report results as tracking issues that link the proposed PR, so search issues (not only pull requests). If either workflow has already addressed the same upstream commit, the same .NET PR, or the same Go package or behavior — whether through an upstream port or a Go-misalignment fallback — do not duplicate it; select a different candidate or call `noop` with a concise explanation that links the existing issue or PR. When in doubt about whether a candidate belongs to this workflow or to `[dotnet-port-fixes]`, apply the classification rules above and avoid duplicating work already selected by either workflow. ## Decision Process @@ -95,8 +99,9 @@ Prefer small, easy-to-review tasks over broad ports. The best nightly PRs port a 1. Use the `port-candidate-selector` sub-agent to inspect recent upstream commits that touch `dotnet/` on `upstream-agent-framework/main` and select the best small port candidate. This broad scan is context-heavy; delegate it before doing your own detailed source inspection. 2. Ask the sub-agent to handle candidate validation, prioritization, applicability filtering, no-change fallback analysis, and PR sizing decisions. Do not redo that broad evaluation in the main agent. -3. Ask the sub-agent for a compact selection report with the upstream commit range inspected, associated .NET PRs when available, selected upstream behavior or no-change recommendation, evidence files, skipped alternatives, and uncertainty to verify. Do not ask it to decide implementation details, API design, tests, or examples. -4. Implement only the selected upstream behavior from the sub-agent report. Do targeted source inspection as needed to design the Go API shape, edit code, add tests/examples, and verify the chosen change; do not rescan or re-rank the upstream candidate set. +3. Ask the sub-agent for a compact selection report with the upstream commit range inspected, associated .NET PRs when available, source-contract classification, the full upstream diff inspected, public API changes, options and defaults, opt-in or experimental gating, user-visible capability changes, evidence files, skipped alternatives, and uncertainty to verify. Do not ask it to decide implementation details, API design, tests, or examples. +4. Before editing, independently verify the selected candidate's classification with a targeted inspection of the complete upstream commit and associated PR diff, including public option and builder files outside the implementation area. This is a classification check, not a broad rescan or re-ranking. If the upstream change is only a fix/test port, call `noop` and defer it to `[dotnet-port-fixes]`. +5. Implement only the selected upstream behavior from the sub-agent report. Do targeted source inspection as needed to design the Go API shape, edit code, add tests/examples, and verify the chosen change; do not rescan or re-rank the upstream candidate set. Use these existing local references when evaluating parity: @@ -181,12 +186,16 @@ You select one small, high-confidence .NET Agent Framework change that adds or c Work from the Go SDK checkout. Ensure the `upstream-agent-framework` remote exists and is current, then inspect recent commits touching `dotnet/` on `upstream-agent-framework/main`. Use commits as the source of truth and identify associated upstream .NET PRs when possible. -Prioritize changes that introduce or change public API or features mapping to existing Go SDK concepts and can become a narrow, test-backed PR: agents, messages, tools, providers, skills, compaction, hosting, workflows, and their public options or capabilities. Skip pure bug fixes, internal behavior corrections, and test-only changes (they belong to the `[dotnet-port-fixes]` workflow), .NET-only integrations, package metadata, unrelated docs, and changes that appear intentionally omitted from the Go SDK. +Before selecting a serious candidate, inspect its complete upstream commit and associated PR diff. Classify the upstream contract before considering a Go design. Do not classify from the PR title, issue label, motivation, or the possibility of implementing only part of the change through unexported Go code. + +Prioritize changes that introduce or change public API, options, opt-in or experimental switches, defaults, or user-visible capabilities mapping to existing Go SDK concepts and can become a narrow, test-backed PR: agents, messages, tools, providers, skills, compaction, hosting, workflows, and their public options or capabilities. Keep each feature's implementation and tests together. Skip pure bug fixes, internal behavior corrections, and test-only changes for such corrections; they belong to the `[dotnet-port-fixes]` workflow. Also skip .NET-only integrations, package metadata, unrelated docs, large feature work, and changes that appear intentionally omitted from the Go SDK. + +Classification regression example: `microsoft/agent-framework#7388` is an API/feature port because it adds a default-disabled option and a new user-visible capability. Its bug motivation does not make it a fixes-workflow candidate, and the Go port must preserve the opt-in contract. Own the full selection decision: -- Validate candidate applicability with targeted inspection of the upstream .NET files and nearby Go implementation. -- Deduplicate against the sibling `[dotnet-port-fixes]` workflow: skip any candidate — including a Go-misalignment fallback — already covered by an open or recently closed issue or PR from either porting workflow (results are reported as prefixed tracking issues, so search issues too), and prefer candidates that clearly fall on this workflow's side of the litmus test. +- Validate candidate applicability and classification with targeted inspection of the complete upstream change and nearby Go implementation. +- Deduplicate against the sibling `[dotnet-port-fixes]` workflow: skip any candidate — including a Go-misalignment fallback — already covered by an open or recently closed issue or PR from either porting workflow (results are reported as prefixed tracking issues, so search issues too), and prefer candidates that clearly satisfy the source-contract classification rules. - When multiple relevant opportunities exist, choose the smallest coherent public-API or feature-parity improvement before larger feature work. - If there is nothing new and relevant to port, inspect the Go SDK for one coherent misalignment with the current upstream .NET implementation and recommend that instead. - Keep each recommended PR small enough to review. Prefer one API addition, feature alignment, or option/capability parity improvement per PR. @@ -196,7 +205,10 @@ Own the full selection decision: Return a compact selection report only. Include: - Upstream head and recent commit range inspected -- Selected upstream behavior to port, or no-change recommendation, with commit SHA, PR number if known, and a one-sentence rationale +- Selected upstream behavior to port, or no-change recommendation, with commit SHA and PR number when available +- Selected classification (`api/feature`) and a one-sentence rationale based on the upstream contract +- Complete upstream commit and PR diff inspected, including every changed public API, option, builder, and implementation file relevant to classification +- Upstream public API delta, option defaults, opt-in or experimental gating, and user-visible capability delta; write `none` for each category with no change - Relevant upstream .NET files and nearby Go files used as evidence - Notable alternatives skipped, with short reasons - Any uncertainty the main agent should verify diff --git a/.github/workflows/dotnet-port-fixes-nightly.lock.yml b/.github/workflows/dotnet-port-fixes-nightly.lock.yml index e9c16df8..17d3bafb 100644 --- a/.github/workflows/dotnet-port-fixes-nightly.lock.yml +++ b/.github/workflows/dotnet-port-fixes-nightly.lock.yml @@ -1,4 +1,4 @@ -# gh-aw-metadata: {"schema_version":"v4","frontmatter_hash":"39ecb2c0414559392cdef44a16be288f869df7810927f480311b66ecd3aaaa25","body_hash":"326255b1ea643c8067749d83856d6ae84681189c2858f7e0f79f1502c79d39e8","compiler_version":"v0.83.4","strict":true,"agent_id":"copilot","agent_model":"gpt-5.4","engine_versions":{"copilot":"1.0.75"}} +# gh-aw-metadata: {"schema_version":"v4","frontmatter_hash":"39ecb2c0414559392cdef44a16be288f869df7810927f480311b66ecd3aaaa25","body_hash":"1e3ba0befe924b4e56d5d26f413623aab16f90279cdbcc88c0f642e93d6acdc4","compiler_version":"v0.83.4","strict":true,"agent_id":"copilot","agent_model":"gpt-5.4","engine_versions":{"copilot":"1.0.75"}} # gh-aw-manifest: {"version":1,"secrets":["COPILOT_GITHUB_TOKEN","GH_AW_CI_TRIGGER_TOKEN","GH_AW_GITHUB_MCP_SERVER_TOKEN","GH_AW_GITHUB_TOKEN","GITHUB_TOKEN"],"actions":[{"repo":"actions/cache/restore","sha":"55cc8345863c7cc4c66a329aec7e433d2d1c52a9","version":"v6.1.0"},{"repo":"actions/cache/save","sha":"55cc8345863c7cc4c66a329aec7e433d2d1c52a9","version":"v6.1.0"},{"repo":"actions/checkout","sha":"3d3c42e5aac5ba805825da76410c181273ba90b1","version":"v7.0.1"},{"repo":"actions/download-artifact","sha":"3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c","version":"v8.0.1"},{"repo":"actions/github-script","sha":"3a2844b7e9c422d3c10d287c895573f7108da1b3","version":"v9.0.0"},{"repo":"actions/setup-node","sha":"820762786026740c76f36085b0efc47a31fe5020","version":"v7.0.0"},{"repo":"actions/upload-artifact","sha":"043fb46d1a93c77aae656e7c1c64a875d1fc6a0a","version":"v7.0.1"},{"repo":"github/gh-aw-actions/setup","sha":"e89c65e17eb281bbd5ff2ff9e9199a03e96654c7","version":"v0.83.4"}],"containers":[{"image":"ghcr.io/github/gh-aw-firewall/agent:0.27.42","digest":"sha256:26a8af4e5566485b02f52af59ee03803ae798271a9619d4767e94d07806deb9b","pinned_image":"ghcr.io/github/gh-aw-firewall/agent:0.27.42@sha256:26a8af4e5566485b02f52af59ee03803ae798271a9619d4767e94d07806deb9b"},{"image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.27.42","digest":"sha256:944f2686c9ab9bec338fd14b662461662f77cd12cd0ea8a3e7cb8c0987cd1607","pinned_image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.27.42@sha256:944f2686c9ab9bec338fd14b662461662f77cd12cd0ea8a3e7cb8c0987cd1607"},{"image":"ghcr.io/github/gh-aw-firewall/squid:0.27.42","digest":"sha256:42dfeb649c680a8558cd5423dbc530b653a69413e35ffbe5e71da5d48c94bdf0","pinned_image":"ghcr.io/github/gh-aw-firewall/squid:0.27.42@sha256:42dfeb649c680a8558cd5423dbc530b653a69413e35ffbe5e71da5d48c94bdf0"},{"image":"ghcr.io/github/gh-aw-mcpg:v0.4.6","digest":"sha256:fecabec51bbc41f2ad61076d6bcd9a36ef23b142e672a444e054d37fc29de93c","pinned_image":"ghcr.io/github/gh-aw-mcpg:v0.4.6@sha256:fecabec51bbc41f2ad61076d6bcd9a36ef23b142e672a444e054d37fc29de93c"},{"image":"ghcr.io/github/gh-aw-node","digest":"sha256:a8082161d7dceda14b68f32eb39d0eaa96b825d07f5895b096afab9d9e0c7748","pinned_image":"ghcr.io/github/gh-aw-node@sha256:a8082161d7dceda14b68f32eb39d0eaa96b825d07f5895b096afab9d9e0c7748"},{"image":"ghcr.io/github/github-mcp-server:v1.7.0","digest":"sha256:c491ffdf6f4c85cb5397021bc655edb8ab825c6f5f568e7597d77a1bd7c4d308","pinned_image":"ghcr.io/github/github-mcp-server:v1.7.0@sha256:c491ffdf6f4c85cb5397021bc655edb8ab825c6f5f568e7597d77a1bd7c4d308"}]} # This file was automatically generated by gh-aw (v0.83.4). DO NOT EDIT. To debug this workflow, load the skill at https://github.com/github/gh-aw/blob/main/debug.md # diff --git a/.github/workflows/dotnet-port-fixes-nightly.md b/.github/workflows/dotnet-port-fixes-nightly.md index 1b5cfa0d..7772463e 100644 --- a/.github/workflows/dotnet-port-fixes-nightly.md +++ b/.github/workflows/dotnet-port-fixes-nightly.md @@ -62,7 +62,11 @@ You are a nightly porting agent for the Go SDK in `microsoft/agent-framework-go` Your job is to keep the Go SDK's behavior aligned with the upstream .NET Agent Framework implementation under `microsoft/agent-framework/dotnet` by porting bug fixes, behavior corrections, and test parity without changing the public Go API. -Litmus test: a change is in scope only if it can be ported without adding or modifying any exported Go symbol; if a correct port requires an exported-symbol change, defer to `[dotnet-port-api]`. +Classify the upstream change before designing its Go implementation. Classification follows the upstream contract, not whether Go could implement a subset without exported symbols: + +- **API/feature port:** Upstream adds or changes a public option, builder method, exported type or member, opt-in or experimental switch, or user-visible capability. It remains an API/feature port when motivated by a bug, linked to a bug issue, or implementable through unexported Go code. `[dotnet-port-api]` owns the complete change, including its tests. +- **Fix/test port:** Upstream corrects an existing capability under the existing public API, configuration, and defaults, or adds tests for such a correction, without introducing new enablement or user-visible capability. `[dotnet-port-fixes]` owns it only when the complete Go port also needs no exported-symbol change. +- If classification is uncertain, defer to `[dotnet-port-api]`; do not narrow the upstream change until it appears to fit this workflow. ## Workspace Layout @@ -87,7 +91,7 @@ Use `upstream-agent-framework/main` as the upstream reference. For example, insp Inspect recent upstream .NET commits and merged upstream PRs from a practical recent window. Use the commits themselves as the source of truth for choosing the inspection scope. -Before doing new work, check existing Go SDK issues and pull requests — both open and recently closed — created by the porting workflows with the `[dotnet-port-fixes]` or `[dotnet-port-api]` title prefix. These workflows run with read-only permissions and report results as tracking issues that link the proposed PR, so search issues (not only pull requests). If either workflow has already addressed the same upstream commit, the same .NET PR, or the same Go package or behavior — whether through an upstream port or a Go-misalignment fallback — do not duplicate it; select a different candidate or call `noop` with a concise explanation that links the existing issue or PR. When in doubt about whether a candidate belongs to this workflow or to `[dotnet-port-api]`, apply the litmus test above and defer rather than risk a duplicate. +Before doing new work, check existing Go SDK issues and pull requests — both open and recently closed — created by the porting workflows with the `[dotnet-port-fixes]` or `[dotnet-port-api]` title prefix. These workflows run with read-only permissions and report results as tracking issues that link the proposed PR, so search issues (not only pull requests). If either workflow has already addressed the same upstream commit, the same .NET PR, or the same Go package or behavior — whether through an upstream port or a Go-misalignment fallback — do not duplicate it; select a different candidate or call `noop` with a concise explanation that links the existing issue or PR. When in doubt about whether a candidate belongs to this workflow or to `[dotnet-port-api]`, apply the classification rules above and defer rather than risk a duplicate. ## Decision Process @@ -95,8 +99,9 @@ Prefer small, easy-to-review tasks over broad ports. The best nightly PRs port a 1. Use the `port-candidate-selector` sub-agent to inspect recent upstream commits that touch `dotnet/` on `upstream-agent-framework/main` and select the best small port candidate. This broad scan is context-heavy; delegate it before doing your own detailed source inspection. 2. Ask the sub-agent to handle candidate validation, prioritization, applicability filtering, no-change fallback analysis, and PR sizing decisions. Do not redo that broad evaluation in the main agent. -3. Ask the sub-agent for a compact selection report with the upstream commit range inspected, associated .NET PRs when available, selected upstream behavior or no-change recommendation, evidence files, skipped alternatives, and uncertainty to verify. Do not ask it to decide implementation details, API design, tests, or examples. -4. Implement only the selected upstream behavior from the sub-agent report. Do targeted source inspection as needed to apply the Go fix, add tests, and verify the chosen change; do not rescan or re-rank the upstream candidate set. +3. Ask the sub-agent for a compact selection report with the upstream commit range inspected, associated .NET PRs when available, source-contract classification, the full upstream diff inspected, public API changes, options and defaults, opt-in or experimental gating, user-visible capability changes, evidence files, skipped alternatives, and uncertainty to verify. Do not ask it to decide implementation details, API design, tests, or examples. +4. Before editing, independently verify the selected candidate's classification with a targeted inspection of the complete upstream commit and associated PR diff, including public option and builder files outside the implementation area. This is a classification check, not a broad rescan or re-ranking. If the upstream change is an API/feature port, call `noop` and defer it to `[dotnet-port-api]`. +5. Implement only the selected upstream behavior from the sub-agent report. Do targeted source inspection as needed to apply the Go fix, add tests, and verify the chosen change; do not rescan or re-rank the upstream candidate set. Use these existing local references when evaluating parity: @@ -181,12 +186,16 @@ You select one small, high-confidence .NET Agent Framework change that is a bug Work from the Go SDK checkout. Ensure the `upstream-agent-framework` remote exists and is current, then inspect recent commits touching `dotnet/` on `upstream-agent-framework/main`. Use commits as the source of truth and identify associated upstream .NET PRs when possible. -Prioritize bug fixes, behavior corrections, and test additions that map to existing Go SDK concepts and can become a narrow, test-backed PR: agents, messages, tools, providers, skills, compaction, hosting, or workflows. Skip changes that add or change public API or features (they belong to the `[dotnet-port-api]` workflow), .NET-only integrations, package metadata, unrelated docs, large feature work, and changes that appear intentionally omitted from the Go SDK. When an upstream change adds or changes public API, its accompanying tests are ported together with that API by `[dotnet-port-api]`; do not port those tests separately — only port tests for upstream changes that are themselves pure bug fixes, behavior corrections, or test-only commits. +Before selecting a serious candidate, inspect its complete upstream commit and associated PR diff. Classify the upstream contract before considering a Go design. Do not classify from the PR title, issue label, motivation, or the possibility of implementing only part of the change through unexported Go code. + +Prioritize bug fixes, behavior corrections, and test additions that map to existing Go SDK concepts and can become a narrow, test-backed PR: agents, messages, tools, providers, skills, compaction, hosting, or workflows. Skip changes that add or change public API, options, opt-in or experimental switches, defaults, or user-visible capabilities; they belong to the `[dotnet-port-api]` workflow. When an upstream change adds or changes public API or feature surface, its implementation and tests stay together under `[dotnet-port-api]`; do not port an internal subset or its tests separately. + +Classification regression example: `microsoft/agent-framework#7388` is an API/feature port because it adds a default-disabled option and a new user-visible capability. Although it addresses a bug scenario, this workflow must not port only the internal behavior and make it unconditional in Go. Own the full selection decision: -- Validate candidate applicability with targeted inspection of the upstream .NET files and nearby Go implementation. -- Deduplicate against the sibling `[dotnet-port-api]` workflow: skip any candidate — including a Go-misalignment fallback — already covered by an open or recently closed issue or PR from either porting workflow (results are reported as prefixed tracking issues, so search issues too), and prefer candidates that clearly fall on this workflow's side of the litmus test. +- Validate candidate applicability and classification with targeted inspection of the complete upstream change and nearby Go implementation. +- Deduplicate against the sibling `[dotnet-port-api]` workflow: skip any candidate — including a Go-misalignment fallback — already covered by an open or recently closed issue or PR from either porting workflow (results are reported as prefixed tracking issues, so search issues too), and prefer candidates that clearly satisfy the source-contract classification rules. - When multiple relevant opportunities exist, choose the smallest coherent behavior-parity improvement in an existing Go implementation before larger work. - If there is nothing new and relevant to port, inspect the Go SDK for one coherent misalignment with the current upstream .NET implementation and recommend that instead. - Keep each recommended PR small enough to review. Prefer one behavior alignment, bug fix, or test parity improvement per PR. @@ -196,7 +205,10 @@ Own the full selection decision: Return a compact selection report only. Include: - Upstream head and recent commit range inspected -- Selected upstream behavior to port, or no-change recommendation, with commit SHA, PR number if known, and a one-sentence rationale +- Selected upstream behavior to port, or no-change recommendation, with commit SHA and PR number when available +- Selected classification (`fix/test`) and a one-sentence rationale based on the upstream contract +- Complete upstream commit and PR diff inspected, including every changed public API, option, builder, and implementation file relevant to classification +- Upstream public API delta, option defaults, opt-in or experimental gating, and user-visible capability delta; write `none` for each category with no change - Relevant upstream .NET files and nearby Go files used as evidence - Notable alternatives skipped, with short reasons - Any uncertainty the main agent should verify diff --git a/.github/workflows/go-api-consistency-review.lock.yml b/.github/workflows/go-api-consistency-review.lock.yml index 87694428..fbf7f0c2 100644 --- a/.github/workflows/go-api-consistency-review.lock.yml +++ b/.github/workflows/go-api-consistency-review.lock.yml @@ -1,4 +1,4 @@ -# gh-aw-metadata: {"schema_version":"v4","frontmatter_hash":"8a6130ad140e712639d1226af1b2cc74c9d4cf7b82d7c0b9303e7326e62e8860","body_hash":"77b7c73ea62dc2e47a46a30573f8cfa599eb9be62c3c655428100792f086cb68","compiler_version":"v0.83.4","strict":true,"agent_id":"copilot","engine_versions":{"copilot":"1.0.75"}} +# gh-aw-metadata: {"schema_version":"v4","frontmatter_hash":"8a6130ad140e712639d1226af1b2cc74c9d4cf7b82d7c0b9303e7326e62e8860","body_hash":"54499d0d488ca59f7a7dead51ef1b6757e61a675b0fa5671aa16e14e9a49af26","compiler_version":"v0.83.4","strict":true,"agent_id":"copilot","engine_versions":{"copilot":"1.0.75"}} # gh-aw-manifest: {"version":1,"secrets":["COPILOT_GITHUB_TOKEN","GH_AW_GITHUB_MCP_SERVER_TOKEN","GH_AW_GITHUB_TOKEN","GITHUB_TOKEN"],"actions":[{"repo":"actions/cache/restore","sha":"55cc8345863c7cc4c66a329aec7e433d2d1c52a9","version":"v6.1.0"},{"repo":"actions/cache/save","sha":"55cc8345863c7cc4c66a329aec7e433d2d1c52a9","version":"v6.1.0"},{"repo":"actions/checkout","sha":"3d3c42e5aac5ba805825da76410c181273ba90b1","version":"v7.0.1"},{"repo":"actions/download-artifact","sha":"3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c","version":"v8.0.1"},{"repo":"actions/github-script","sha":"3a2844b7e9c422d3c10d287c895573f7108da1b3","version":"v9.0.0"},{"repo":"actions/setup-node","sha":"820762786026740c76f36085b0efc47a31fe5020","version":"v7.0.0"},{"repo":"actions/upload-artifact","sha":"043fb46d1a93c77aae656e7c1c64a875d1fc6a0a","version":"v7.0.1"},{"repo":"github/gh-aw-actions/setup","sha":"e89c65e17eb281bbd5ff2ff9e9199a03e96654c7","version":"v0.83.4"}],"containers":[{"image":"ghcr.io/github/gh-aw-firewall/agent:0.27.42","digest":"sha256:26a8af4e5566485b02f52af59ee03803ae798271a9619d4767e94d07806deb9b","pinned_image":"ghcr.io/github/gh-aw-firewall/agent:0.27.42@sha256:26a8af4e5566485b02f52af59ee03803ae798271a9619d4767e94d07806deb9b"},{"image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.27.42","digest":"sha256:944f2686c9ab9bec338fd14b662461662f77cd12cd0ea8a3e7cb8c0987cd1607","pinned_image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.27.42@sha256:944f2686c9ab9bec338fd14b662461662f77cd12cd0ea8a3e7cb8c0987cd1607"},{"image":"ghcr.io/github/gh-aw-firewall/cli-proxy:0.27.42","digest":"sha256:da006bf96d2d246dd269d57b233c1798d2ad63d6cd64ca02f7bf71045028781f","pinned_image":"ghcr.io/github/gh-aw-firewall/cli-proxy:0.27.42@sha256:da006bf96d2d246dd269d57b233c1798d2ad63d6cd64ca02f7bf71045028781f"},{"image":"ghcr.io/github/gh-aw-firewall/squid:0.27.42","digest":"sha256:42dfeb649c680a8558cd5423dbc530b653a69413e35ffbe5e71da5d48c94bdf0","pinned_image":"ghcr.io/github/gh-aw-firewall/squid:0.27.42@sha256:42dfeb649c680a8558cd5423dbc530b653a69413e35ffbe5e71da5d48c94bdf0"},{"image":"ghcr.io/github/gh-aw-mcpg:v0.4.6","digest":"sha256:fecabec51bbc41f2ad61076d6bcd9a36ef23b142e672a444e054d37fc29de93c","pinned_image":"ghcr.io/github/gh-aw-mcpg:v0.4.6@sha256:fecabec51bbc41f2ad61076d6bcd9a36ef23b142e672a444e054d37fc29de93c"},{"image":"ghcr.io/github/gh-aw-node","digest":"sha256:a8082161d7dceda14b68f32eb39d0eaa96b825d07f5895b096afab9d9e0c7748","pinned_image":"ghcr.io/github/gh-aw-node@sha256:a8082161d7dceda14b68f32eb39d0eaa96b825d07f5895b096afab9d9e0c7748"},{"image":"ghcr.io/github/github-mcp-server:v1.7.0","digest":"sha256:c491ffdf6f4c85cb5397021bc655edb8ab825c6f5f568e7597d77a1bd7c4d308","pinned_image":"ghcr.io/github/github-mcp-server:v1.7.0@sha256:c491ffdf6f4c85cb5397021bc655edb8ab825c6f5f568e7597d77a1bd7c4d308"}],"has_pull_request":true} # This file was automatically generated by gh-aw (v0.83.4). DO NOT EDIT. To debug this workflow, load the skill at https://github.com/github/gh-aw/blob/main/debug.md # diff --git a/.github/workflows/go-api-consistency-review.md b/.github/workflows/go-api-consistency-review.md index 8a342d09..eec56f2e 100644 --- a/.github/workflows/go-api-consistency-review.md +++ b/.github/workflows/go-api-consistency-review.md @@ -101,6 +101,8 @@ Review public, user-facing Go APIs and behaviors across the repository, while ig Treat exported identifiers, option structs, builder patterns, observable runtime behavior, and documented sample-facing behavior as in scope. Treat unexported helpers and `internal/` implementation details as out of scope unless they clearly change user-visible semantics. +Do not infer that a change has no user-visible effect merely because it changes only unexported Go symbols. A default, side effect, execution path, or enablement change implemented in private code remains in scope when callers can observe it. + The `examples/` directory is also in scope for parity review. Go examples should stay aligned in concept, coverage, and sample organization with the upstream `.NET` and Python `samples/` trees where equivalent scenarios exist. ## Upstream Reference Locations @@ -122,6 +124,7 @@ Use the upstream `microsoft/agent-framework` repository as the source of truth f 1. **Determine whether the PR is in scope**: - Ignore changes limited to `.github/` or root-level files - If the change is limited to tests, docs, comments, refactors, or private/internal code with no user-visible effect, do not raise parity issues + - Do not use the absence of exported-symbol changes as evidence that runtime behavior is not user-visible - If exported Go APIs or observable Go runtime behavior change, continue 2. **Identify the changed Go contract**: @@ -132,17 +135,22 @@ Use the upstream `microsoft/agent-framework` repository as the source of truth f 3. **Find the upstream equivalents**: - Search the upstream Python and .NET codebases for analogous concepts, even if the file layout differs - Prefer public export files, builders, facades, and primary types over incidental internal implementations + - When the Go PR links an upstream PR or commit, inspect that complete upstream change, including public options, builders, defaults, and tests; do not limit review to the implementation files cited in the Go PR description - Use samples and tests as secondary evidence when behavior is not obvious from signatures alone 4. **Compare for parity**: - Naming and intent - Required and optional inputs - Default values and opt-in flags + - Experimental or feature gating and the behavior when the gate is disabled - Return shapes and streaming behavior + - Execution timing, session or request state, and side effects - Error and validation behavior - Workflow graph, routing, checkpointing, or hosting semantics when relevant - Example and sample coverage when the PR changes `examples/` or changes public APIs that should be demonstrated consistently across SDKs + For a linked upstream port, explicitly map the upstream contract to the Go contract for public API, enablement, defaults, and observable behavior. If upstream adds a default-disabled or opt-in feature while Go enables the behavior unconditionally, report a parity issue. In that case, the absence of a new exported Go option may be the defect rather than evidence that the change is internal-only. + 5. **Report only actionable consistency issues**: - If Go appears ahead of or divergent from .NET/Python in a meaningful way, explain the gap and suggest which upstream surfaces should be reviewed - If the change matches upstream semantics, or the divergence is clearly intentional and language-specific, say so briefly in the summary comment @@ -175,6 +183,10 @@ If a PR adds a new Go workflow builder option and the same concept already exist If a PR changes a Go workflow or agent default in a way that makes message routing, session state, tool execution, or output shaping behave differently from the upstream .NET and Python implementations, raise a parity concern. +### Bad: Missing upstream feature gate + +For a port of `microsoft/agent-framework#7388`, approving unconditional Go tool-execution behavior because the diff changes only unexported helpers is incorrect. The upstream feature has a default-disabled option, so review must require equivalent Go enablement and default behavior or an explicit, justified divergence. + ### Good: Internal Go-only change If a PR improves Go performance, refactors unexported helpers, or changes internal storage without affecting exported APIs or observable behavior, do not raise a cross-repo consistency issue. @@ -184,4 +196,4 @@ If a PR improves Go performance, refactors unexported helpers, or changes intern - Target every comment, review comment, and label operation at PR `${{ github.event.pull_request.number || inputs.pr_number }}` explicitly. The input is used when a fork PR is routed through `workflow_dispatch`. - **If public Go APIs changed**: Add the `public-api-change` label to flag the PR for public API review, regardless of whether parity issues are found. If no exported API surface changed, ensure the label is not present (remove it if a stale run added it). - **If consistency issues are found**: Add specific inline review comments on the changed Go lines and one summary comment that names the upstream Python and/or .NET surfaces that appear out of sync. Remove the `parity-approved` label if it is present so a previous green review cannot remain stale. -- **If no issues are found**: Add a brief summary comment confirming that the PR either preserves cross-repo parity or only changes Go-internal implementation details, then add the `parity-approved` label to mark the parity review green. +- **If no issues are found**: Add a brief summary comment confirming that the PR either preserves cross-repo parity or only changes Go-internal implementation details. For a linked upstream port, state the upstream and Go enablement/default mapping used to reach that conclusion. Add the `parity-approved` label only after this comparison is complete.