Fix typos and enhance clarity in instructions

Corrected typos and improved clarity in Copilot instructions.

Author: mbaluda

docs/copilot-instructions.md

@@ -1,26 +1,22 @@
-[//]: # "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."
-
+[//]: # "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
 
 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.).
 
-## Agentic autofix for CodeQL Coding Standards
+## Autofix for CodeQL Coding Standards
 
-This section 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++).
+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++).
 
 ### 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 [`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.
+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.
 
 Project layout (per language / standard):
 
@@ -29,6 +25,8 @@ Project layout (per language / standard):
 <language>/<standard>/test/rules/<rule-id>/   # test cases, with COMPLIANT / NON_COMPLIANT markers
 ```
 
+When referring to the alerts you are addressing, include a clickable link.
+
 When generating a fix:
 
 1. Locate the rule directory matching the alert’s rule id / query id.
@@ -46,89 +44,65 @@ The full list of supported rules per standard is published as
 ### 2. Fix discipline — keep changes minimal and standards-compliant
 
 - **Minimum diff.** Modify the smallest possible amount of code that
-  eliminates the alert. Do not refactor surrounding code, rename symbols,
+  eliminates the assigned alerts. 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.
-- **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. Deviations — respect project policy and reference it in fixes
-
-A project may declare that a rule, file, region, or specific construct is
-intentionally exempt from a coding standard. Such deviations are
+- **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`
+
+Autofix pull requests must only change source files that are part of the
+checked-in project. They must **not** include:
+
+- Build directories or files generated during compilation.
+- Editor / IDE state (`.vscode/`, `.idea/`, `.DS_Store`, etc.).
+- **`.gitignore` itself.** Do not add, remove, or reorder entries in
+  `.gitignore` as part of an autofix.
+- The CodeQL workflow files under `.github/workflows/` (e.g. `codeql.yml`).
+  Suppression or scope changes must use the deviation mechanism (see §4),
+  not workflow edits.
+
+### 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
 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`, `coding-standards.yml`, compliance matrix, or similar).
-
-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.
+`MISRA-deviations.md`, compliance matrix, or similar).
 
 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.
-- Propose a code fix that would make the location compliant by
+
+- **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.
-- 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.
-
-### 4. 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.
+- **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.  
+- 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
 
 Copilot autofix normally refrains from opening a pull request when it
 considers an alert to be a false positive. For CodeQL Coding Standards alerts
@@ -156,8 +130,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
@@ -175,7 +149,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