Refactor Copilot instructions for clarity and consistency

Author: mbaluda

docs/copilot-instructions.md

@@ -1,22 +1,20 @@
-[//]: # "Include this file in the repository to provide instructions to GitHub Copilot AUtofix. For more information, see https://docs.github.com/copilot/copilot-for-business/copilot-instructions."
-# GitHub Copilot instructions
+[//]: # "Include this file in the repository to provide instructions to GitHub Copilot Autofix. For more information, see https://docs.github.com/copilot/copilot-for-business/copilot-instructions."
 
-This file contains repository-wide guidance for GitHub Copilot. Each top-level
-section below configures Copilot for a specific use case in this repository.
-Add further top-level sections as needed (general coding conventions, review
-guidance, etc.).
 
-## Autofix for CodeQL Coding Standards
+# Agentic autofix instructions for CodeQL Coding Standards
 
-This section configures GitHub Copilot **Autofix** when it generates pull requests to remediate alerts produced by the
-[CodeQL Coding Standards](https://github.com/github/codeql-coding-standards/)
-project. It applies to alerts for any of the supported standards (MISRA C,
-MISRA C++, AUTOSAR C++, CERT C, CERT C++).
+This document configures **Agentic Autofix** when generating pull requests to
+remediate alerts produced by [CodeQL Coding Standards](https://github.com/github/codeql-coding-standards/).
+It applies to alerts for any of the supported standards (MISRA C, MISRA C++,
+AUTOSAR C++, CERT C, CERT C++).
 
-### 1. Reference material — where to learn each rule
+## 1. Reference material — where to learn each rule
 
-Before proposing a fix, consult the rule’s authoritative implementation as well as the corresponding compliant and non-compliant code patterns available as test cases in the CodeQL Coding Standards [`github/codeql-coding-standards`](https://github.com/github/codeql-coding-standards/)
-repository. That repository is the single source of truth for what the query detects and what compliant code looks like.
+Before proposing a fix, consult the rule’s authoritative implementation as well
+as the corresponding compliant and non-compliant code patterns available as
+test cases in the [`github/codeql-coding-standards` repository](https://github.com/github/codeql-coding-standards/).
+That repository is the single source of truth for what the query
+detects and what compliant code looks like.
 
 Project layout (per language / standard):
 
@@ -41,33 +39,48 @@ The full list of supported rules per standard is published as
 `supported_rules_list_<version>.csv` / `.md` in each
 [release](https://github.com/github/codeql-coding-standards/releases).
 
-### 2. Fix discipline — keep changes minimal and standards-compliant
+## 2. Fix discipline — keep changes minimal and standards-compliant
 
 - **Minimum diff.** Modify the smallest possible amount of code that
-  eliminates the assigned alerts. Do not refactor surrounding code, rename symbols,
+  eliminates the alert. Do not refactor surrounding code, rename symbols,
   reformat unrelated lines, or change public APIs unless strictly required to
   satisfy the rule.
 - **No drive-by changes.** Do not add features, fix unrelated warnings, change
   build flags, update dependencies, or “improve” code that the alert does not
   point at.
-- **New code must comply with the analyzed coding standard.** Any code introduced by the
-  fix must itself satisfy every rule of the coding standard being verified
-  (e.g. all MISRA C rules). Do not limit the review to the rule targeted by
-  the alert: iterate over the full supported rules list for the applicable
-  standard and, for each rule, read its help file
-  (`<language>/<standard>/src/rules/<rule-id>/<rule-id>.md` or `.qhelp`) to
-  understand its intent, then verify that the introduced code does not violate
-  it. Cross-check against the COMPLIANT examples in each rule's
-  `test/rules/<rule-id>/` directory.
-- **Match the project’s existing style.** Follow the conventions visible in
-  the surrounding source files (naming, headers, namespaces, C++ standard
-  level, use of `enum class`, etc.).
-- **Preserve behaviour.** A coding-standards fix is a refactor at the source
-  level, not a functional change. The fix must not alter observable runtime
-  behaviour unless the rule explicitly targets undefined or implementation-
-  defined behaviour that has to change.
-
-### 3. Do not touch build outputs, generated files, or `.gitignore`
+- **Do not attempt at fixing design issues.** A fix should not attempt to
+  “improve” the design of the code or address architectural issues.
+  Always verify that the code section around the alert is intended to follow
+  the standard and add a comment.
+  The presence of certain design issues (e.g. dynamic memory allocation) might
+  indicate that the code is not intended to be compliant with the standard, and
+  that a deviation should be added instead of a code fix.
+- **New code must comply with the same standard.** Any code introduced by the
+  fix must itself satisfy the coding standard being verified (e.g. MISRA C++
+  2023). Cross-check the inserted code against the COMPLIANT examples in the
+  corresponding `test/rules/<rule-id>/` directory and against neighbouring
+  rules that are obviously relevant (e.g. don’t fix an integer-conversion rule
+  by introducing a cast that violates a different MISRA rule).
+- **Preserve safe and desired functional behavior.** ensure the resulting code
+  handles all reasonable real-world scenarios as the code originally intended.
+  This may involve precisely maintaining the existing code behavior, or it may
+  involve fixing subtle or rare bugs, for instance dangerous overflows,
+  that the existing code does not handle and the rule is designed to detect.
+- **Fix dangerous bugs** If the alert is flagging unsafe or undefined behavior,
+  critically examine how that safety issue in the code should be properly fixed.
+  Add detections and error handling if necessary to make the code safe under
+  all conditions without introducing unnecessary complexity. Follow existing
+  project guidelines on how to handle rare, dangerous, or unexpected scenarios
+  that occur at runtime.
+- **Thoroughly explain analysis and functional changes.** If the alert does not
+  introduce any unwanted behavior and the change is functionally equivalent,
+  explain your thinking, and clearly show that the code before was safe, and
+  that the new code is exactly equivalent in behavior.
+  If there was a dangerous edge case or condition, explain exactly how that
+  scenario would create problems in the code and how the fix will prevent such
+  issues and improve the safety and quality of the codebase.
+
+## 3. Do not touch build output, generated files, or `.gitignore`
 
 Autofix pull requests must only change source files that are part of the
 checked-in project. They must **not** include:
@@ -80,29 +93,51 @@ checked-in project. They must **not** include:
   Suppression or scope changes must use the deviation mechanism (see §4),
   not workflow edits.
 
-### 4. Deviations — respect project policy and reference it in fixes
+## 4. Deviations — respect project policy and reference it in fixes
 
-A project under analysis may declare that a rule, file, region, or specific
-construct is intentionally exempt from a coding standard. Such deviations are
+A project may declare that a rule, file, region, or specific construct is
+intentionally exempt from a coding standard. Such deviations are
 not always expressed through the same mechanism: a project may use the
-**standard CodeQL Coding Standards deviation mechanism**, a **custom
-annotation or attribute** convention, **in-source line / block comments**,
+**standard CodeQL Coding Standards deviation mechanism**, a
+**custom annotation or attribute** convention,
+**in-source line / block comments**,
 or a **separate documentation file** (for example a `DEVIATIONS.md`,
-`MISRA-deviations.md`, compliance matrix, or similar).
+`MISRA-deviations.md`, `coding-standards.yml`, compliance matrix, or similar).
 
-If the alert location is covered by an existing deviation:
+Locate the deviations file and explicitly search for matching deviations
+before proposing code changes.
+The fix proposal must take what is found into account and treat it as an
+existing deviation if it clearly covers the alert location and rule.
 
-- **Still propose a code fix** that would make the location compliant by
-  default. Authors may have left the deviation in place pragmatically and
-  may prefer a real fix.
-- **In the pull request description, explicitly state** that a matching
-  deviation already exists in the project, referring to the possible deviation marker
-  so reviewers can decide whether to accept the fix or keep the deviation.
-- If the deviation style does not match the coding standards user manual, propose a fix.  
+If the alert location is covered by an existing deviation:
+- Look for existing deviations of that rule, and see if any should apply
+- In the pull request description, explicitly state that a matching
+  deviation already exists in the project, citing the file path and the
+  relevant `rule-id` / `query-id` / `permit-id` / `code-identifier` / scope
+  (paths or markers) so reviewers can decide whether to accept the fix or
+  keep the deviation.
 - Do not silently delete or weaken an existing deviation, permit, or
   re-categorization entry as part of the fix.
-
-### 5. False positives — propose a deviation, do not stay silent
+- Propose a code fix that would make the location compliant by
+  default. Authors may have left the deviation in place pragmatically and
+  may prefer a real fix.
+- Consider whether an existing code identifier should be used
+- Consider whether a file-wide exception should be used
+- Consider whether a new code identifier should be used
+- If using a code-identifier, look for examples to determine whether 
+  to use [[attribute]] form
+- If using an [[attribute]], look for project formatting configurations or code
+  examples to determine how to format the attribute relative to its declaration
+- When using deviation comments, consider project formatting, the specific
+  violation in question, and other example deviation comments in the project to
+  determine whether to use same-line, next-line, or begin/end comment deviations
+  Project formatting configuration may be .clang-format, etc.
+
+## 5. False positives — propose a deviation, do not stay silent
+
+Precedence: if an alert is judged to be a false positive, the false-positive
+workflow in this section overrides any guidance above about proposing a code
+fix when a deviation exists.
 
 Copilot autofix normally refrains from opening a pull request when it
 considers an alert to be a false positive. For CodeQL Coding Standards alerts
@@ -130,8 +165,8 @@ When an alert is judged to be a false positive, the autofix PR must:
      or directory is affected;
    - a project-wide deviation only when the rule is genuinely inapplicable to
      the project.
-   Use `<standard>` ∈ {`misra`, `autosar`, `cert`} as appropriate for the
-   alert.
+     Use `<standard>` ∈ {`misra`, `autosar`, `cert`} as appropriate for the
+     alert.
 3. **Populate the deviation record** with at least:
    - `rule-id` matching the alert’s rule identifier;
    - `query-id` matching the alert’s `@id` (when the deviation is meant to
@@ -149,7 +184,7 @@ When an alert is judged to be a false positive, the autofix PR must:
 5. **In the PR description**, explicitly state that the alert is being
    handled as a false positive via a deviation (not by code change), link to
    the
-   [deviation mechanism documentation](https://github.com/github/codeql-coding-standards/blob/main/docs/user_manual.md#applying-deviations),
+  [deviation mechanism documentation](https://github.com/github/codeql-coding-standards/blob/main/docs/user_manual.md#applying-deviations),
    and summarise the justification so a reviewer can approve or reject it.
 
 A false-positive PR should therefore contain **only** the deviation entry