diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..1f7549b5 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +.github/workflows/*.lock.yml linguist-generated=true \ No newline at end of file diff --git a/.github/aw/actions-lock.json b/.github/aw/actions-lock.json new file mode 100644 index 00000000..ba426924 --- /dev/null +++ b/.github/aw/actions-lock.json @@ -0,0 +1,9 @@ +{ + "entries": { + "github/gh-aw-actions/setup@v0.86.2": { + "repo": "github/gh-aw-actions/setup", + "version": "v0.86.2", + "sha": "6aab9e5b5c91c615506061f09bedd81a23babe3c" + } + } +} diff --git a/.github/config/.licenserc.yaml b/.github/config/.licenserc.yaml index a492418d..84e0addc 100644 --- a/.github/config/.licenserc.yaml +++ b/.github/config/.licenserc.yaml @@ -8,6 +8,7 @@ header: paths-ignore: - ".github/config" + - ".github/aw" - "**/*.{md,MD}" - "LICENSE" - "NOTICE" diff --git a/.github/workflows/ai-issue-triage.md b/.github/workflows/ai-issue-triage.md new file mode 100644 index 00000000..8da91391 --- /dev/null +++ b/.github/workflows/ai-issue-triage.md @@ -0,0 +1,414 @@ +--- +name: AI Issue Triage + +on: issue labeled ai-triage + +engine: + id: copilot + +model: gpt-5-codex + +permissions: + contents: read + issues: read + copilot-requests: write + +network: defaults + +runtimes: + python: + version: "3.12" + +tools: + bash: true + +pre-agent-steps: + - name: Verify Graphify graph + run: | + test -f .graphify/graph.json || { + echo "::error::.graphify/graph.json does not exist" + exit 1 + } + +mcp-servers: + graphify: + container: "ghcr.io/astral-sh/uv:0.12.7-python3.12-alpine" + entrypoint: "uvx" + entrypointArgs: + - --from + - "graphifyy[mcp]==0.9.48" + - graphify-mcp + - --graph + - /workspace/.graphify/graph.json + mounts: + - \${GITHUB_WORKSPACE}:/workspace:ro + allowed: + - query_graph + - get_node + - get_neighbors + - shortest_path + +safe-outputs: + add-comment: + target: triggering + max: 1 +--- + +# AI Issue Triage + +Analyze the triggering issue: + +${{ steps.sanitized.outputs.text }} + +Your goal is to produce a technical analysis that helps a software engineer: + +- understand the issue; +- understand the relevant parts of the codebase; +- identify the likely impact of the change; +- understand how to approach the implementation; +- identify the tests that should be added or updated; +- obtain a ready-to-use prompt for a coding LLM. + +## Investigation + +Start by understanding the issue and identifying the main concepts involved. + +Use Graphify as the primary navigation tool for the codebase. + +Use the Graphify MCP tools to: + +- find symbols related to the issue; +- inspect relevant nodes; +- inspect callers, callees and neighboring symbols; +- follow relationships between relevant components when useful. + +IMPORTANT: The Graphify MCP server is already configured with the correct +repository graph at startup. When calling any Graphify MCP tool, do not pass +`project_path`; omit it entirely from every Graphify call. Do not pass +`${{ github.workspace }}`, `${GITHUB_WORKSPACE}`, `/workspace`, `.graphify`, or +any repository path as `project_path`. Let the Graphify MCP server use its +configured default graph, which is the authoritative navigation graph for this +workflow. This applies to `query_graph`, `get_node`, `get_neighbors`, and +`shortest_path`. + +Do not treat the Graphify graph as the source of truth. + +After Graphify identifies relevant areas, inspect the actual repository source +code before making conclusions. + +Use the repository filesystem to inspect the relevant files and verify how the +implementation actually works. + +Also inspect relevant Markdown documentation because documentation files are not +represented in the Graphify code graph. + +Look for useful documentation such as: + +- `README.md`; +- files under `docs/`; +- architecture or design documentation; +- configuration and deployment documentation; +- Markdown files located near the affected code. + +Do not read all documentation blindly. + +Use the issue and the code areas identified through Graphify to decide which +documentation is relevant. + +When transport, configuration or runtime infrastructure changes, inspect the +concrete operational surfaces identified by the affected code. Look for +relevant `.env` files, Docker or compose files, broker initialization scripts, +Kubernetes or Helm manifests, CI fixtures, test infrastructure, configuration +examples, README tables and architecture documentation. Use discovered +identifiers such as environment variables, queue or stream names, config fields +and service names to find their consumers. Do not scan the whole repository +blindly. + +If documentation and implementation disagree, treat the current source code as +the source of truth and mention the discrepancy when relevant. + +Continue using Graphify iteratively when additional relationships or affected +components need to be understood. + +### System Boundaries and Contracts + +Recognize when the issue crosses a system boundary, such as a producer and +consumer, queue or stream, message broker, API, RPC, serialization format, +event-driven interface, persistence boundary, external service contract or +protocol/data-format migration. + +When a boundary is involved, investigate the contract and logical semantics, +not only the local implementation. Do not assume that changing a transport or +library preserves the existing behavior. + +When relevant and supported by evidence, determine: + +- the logical unit of work or data; +- whether one logical operation uses one or multiple physical messages, + requests or records; +- framing, metadata and discriminators; +- correlation identifiers and ordering requirements; +- completion or boundary markers; +- deduplication and idempotency expectations; +- acknowledgement, commit, offset or checkpoint semantics; +- retry, replay and partial-processing behavior; +- malformed-input and failure behavior; +- compatibility and versioning requirements. + +Use only the dimensions that matter to the issue. Do not produce a protocol +checklist mechanically when the issue does not provide evidence of stateful or +cross-boundary behavior. + +When analyzing a consumer change, look for the corresponding producer or +upstream contract when it is available. When analyzing a producer change, look +for downstream consumers. Use Graphify relationships, source code, tests, +shared schemas or models, configuration, documentation and local Docker or +test infrastructure to trace that contract. + +If the relevant producer or consumer is in another repository that is not +available, do not invent its behavior. State the required external contract as +an Open Question and name the upstream or downstream component that must be +checked. + +When reusing an existing implementation pattern, distinguish explicitly +between: + +1. structural behavior verified as reusable, such as construction, lifecycle, + callbacks or reconnect handling; +2. behavior that is only analogous; +3. protocol and business semantics that still require independent verification. + +Reuse verified structural patterns, but independently verify protocol and +business semantics. Shared transports, libraries or APIs do not by themselves +establish equivalent message granularity, offset strategy, commit behavior or +replay semantics. + +### Progress and Failure Semantics + +For stateful or replayable code involving ACKs, offsets, checkpoints, +transactions, commits, cursors or persistent progress markers, determine the +logical success boundary: + +- what must complete before progress is acknowledged; +- whether progress applies to one physical input or a larger logical + operation; +- what is replayed after a restart; +- whether early commits can lose data; +- whether late commits can duplicate side effects; +- whether processing is idempotent. + +Do not copy acknowledgement or offset behavior from another consumer without +verifying that its logical unit and failure semantics are the same. + +When malformed input or processing errors are relevant, determine the actual +behavior: log and skip, retry, acknowledge or reject, dead-letter, stop, +continue, restart, replay, or clean up partial state. Label this behavior as +verified or proposed. If the repository and issue do not establish the required +policy, put the decision in Open Questions instead of inventing one. + +If multiple inputs may contribute to one logical result, determine how they are +correlated, where incomplete state is stored, how completion is detected, what +happens to old or incomplete state, whether all expected components are +required, when side effects occur, when progress is committed, and what +happens on restart. Apply this only when repository evidence suggests such +state. + +Prefer the smallest relevant code surface needed to understand the issue. + +Do not propose unrelated refactors or architectural changes unless they are +clearly required by the issue. + +Prefer simple changes that are consistent with the existing codebase and its +current patterns. + +Do not modify repository files. + +Do not create branches, commits or pull requests. + +Do not invent files, symbols, APIs, behavior or implementation details that +cannot be verified from the repository. + +If something cannot be determined confidently, explicitly mention it as an open +question. + +## Output + +After completing a successful triage analysis, you MUST call the `add-comment` +safe-output tool exactly once. Pass the complete `### AI Technical Analysis` +as the body of that `add-comment` call. + +Do not merely return the analysis in the final agent response. Do not assume +normal agent output will automatically become a GitHub comment. Do not call +`noop` after a successful analysis. A successful triage MUST end with exactly +one `add-comment` safe-output request. Use `noop` only when there is genuinely +no actionable analysis to provide. If required information is missing and +prevents a reliable analysis, use the appropriate missing-data behavior. Do +not emit both `add-comment` and `noop` for a successful triage. + +The comment must use the following structure: + +### AI Technical Analysis + +#### Summary + +Briefly explain what the issue appears to require. + +Describe the expected result of the change without going into implementation +details yet. + +#### Relevant Code + +List the main files, symbols, packages and components involved. + +For each relevant item: + +- include the concrete file path when known; +- include the relevant symbol when known; +- briefly explain why it is involved. + +Do not list files that are only loosely related to the issue. + +#### Relevant Documentation + +List documentation that provides useful requirements, architecture, +configuration or implementation context. + +Briefly explain what useful information each document provides. + +Omit this section if no relevant documentation was found. + +#### Current Flow + +Explain how the relevant implementation currently works. + +Describe the execution or data flow when useful. + +Reference concrete files and symbols whenever possible. + +Focus only on the parts necessary to understand the issue. + +#### Implementation Plan + +Provide one concrete, ordered plan for solving the issue. Combine the changes, +locations, reasons, dependencies, compatibility considerations, relevant +implementation patterns, tests and validation in this section. Name concrete +files, packages and symbols whenever known. Prefer exact existing symbols over +generic wording and reuse verified patterns from the repository where possible. + +For each relevant step, include the verified current behavior, the smallest +proposed change, the structural pattern to reuse, and any semantic behavior +that must not be inferred from that pattern. Include ordering or dependency, +compatibility, failure/progress semantics and validation when they affect the +step. Keep steps concise when those dimensions are not relevant. + +Clearly distinguish facts directly confirmed from source, Graphify, +configuration or documentation from the smallest proposed implementation +change. Mark unresolved requirements or decisions as open questions. Do not +present proposals or uncertainties as verified behavior. + +Avoid speculative architecture, invented configuration contracts, new +abstractions that the code does not clearly require, unrelated refactors and +unverified files, symbols or APIs. + +#### Impact + +Describe other components, callers, consumers, data flows or behaviors that +could be affected by the change. + +Use Graphify relationships and the actual source code to identify the likely +impact. + +Distinguish between: + +- directly affected code; +- possible secondary impact. + +Do not claim impact that cannot be supported by the repository. + +#### Tests + +Describe the tests that should be added or updated. + +Include: + +- the main expected behavior; +- regression coverage; +- relevant edge cases; +- integration or end-to-end tests when appropriate. + +Derive tests from the new state transition or failure mode introduced by the +issue, rather than listing generic categories. When supported by the +implementation semantics, consider logical completion boundaries, partial +operations, restart/replay, progress initialization and resume, malformed +input before progress, malformed input after partial state, +ordering/correlation, duplicate input, missing components, shutdown/reconnect +and unchanged downstream behavior. Recommend only the cases relevant to the +issue and avoid inflating the test list. + +Reference existing test files or test patterns when they are relevant. + +Prefer realistic tests over mocks when the existing repository makes that +practical. + +#### Suggested LLM Prompt + +Provide a ready-to-copy prompt that a software engineer can give to a coding LLM +to implement the issue. + +The prompt must be based only on information verified during this analysis and +the proposed steps in the Implementation Plan. + +Include: + +- a concise description of the issue; +- the relevant files, packages and symbols; +- the current behavior; +- the expected behavior; +- the proposed Implementation Plan; +- important implementation constraints; +- tests that should be added or updated; +- relevant edge cases; +- any known compatibility requirements. + +When a system boundary is relevant, carry verified facts about framing, +correlation, logical completion, progress/acknowledgement and replay or failure +behavior into this prompt. If those facts are unresolved, instruct the coding +LLM to verify the producer/consumer contract before implementing. Preserve the +distinction between a structural pattern that can be reused and protocol +semantics that must not be copied without verification. For example, it may be +appropriate to reuse consumer construction while independently verifying its +offset behavior. + +The prompt must explicitly instruct the coding LLM to: + +- inspect the actual repository before modifying code; +- verify that the analysis still matches the current source; +- follow existing repository patterns; +- keep the implementation simple; +- avoid overengineering; +- avoid unrelated refactors; +- avoid inventing APIs, files, symbols or behavior; +- add or update realistic tests; +- explain any necessary deviation from the proposed plan if the actual code + requires it; +- run the relevant tests and validation commands when possible. + +Do not tell the coding LLM that the proposed implementation is guaranteed to be +correct. Keep verified facts, proposed changes and open questions distinct. + +The generated prompt should be directly copy-pasteable. + +Format it inside a fenced text block. + +#### Open Questions + +List anything that cannot be determined confidently from the issue, source code, +Graphify graph or documentation. + +An Open Question must materially affect correctness or compatibility, cannot be +answered from the inspected evidence, and require product, protocol, upstream +or operational clarification. For each one, state the unknown decision, why it +matters, and which component or source should be checked to resolve it. Do not +include low-value speculative questions. + +Omit this section if there are no meaningful open questions.