thorstendb-ARM's changes to copilot instructions

.github/copilot-instructions.md

@@ -21,23 +21,46 @@ Note: `npm run build` already runs lint.
 
 Compiler and tooling settings are defined in `tsconfig.json` and `package.json`. Key conventions to follow:
 
+* Generated code must comply with the project's ESLint and TypeScript rules from the start — do not rely on the linter or formatter to fix style after the fact
 * Prefer explicit types and avoid `any` in production code
 * Keep compliance with `noImplicitAny`, `noImplicitReturns`, `noUnusedLocals`, and `noUnusedParameters`
-* Respect `exactOptionalPropertyTypes`
+* Respect `exactOptionalPropertyTypes`: omit optional properties instead of setting them to `undefined` (use `= {}` or leave out the key)
+* Avoid unnecessary type assertions (`as`) and redundant runtime checks for properties or methods that are guaranteed by the type system; use them only when types are genuinely uncertain (e.g. external data, untyped APIs)
 
 ## Source File Header
 
+Every TypeScript file under `src` and `scripts` must start with this header (adjust the year):
+
+```ts
+/**
+ * Copyright <year or year-range> Arm Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+```
+
 * Keep the existing project copyright/license header at the top of TypeScript files under `src` and `scripts`.
 * For new source files under `src` or `scripts`, add the same copyright/license header format used by nearby files.
 * When editing a file, update the copyright header year or year range if it is outdated.
+  A single year becomes a range (e.g. `2025` -> `2025-2026`); an existing range extends to the current year.
 * Do not remove or reformat license text unless intentionally updating headers repository-wide.
 * If a new source file is completely AI-generated, add `// generated with AI` directly after the header.
 
 ## Naming Conventions
 
 * Variables and functions: `camelCase`
 * Classes, interfaces, and types: `PascalCase`
-* Constants: `UPPER_SNAKE_CASE` for stable constants
+* Constants: `UPPER_SNAKE_CASE` for module-level or static readonly values that act as fixed configuration
 * File names should match exported functionality where applicable
 
 ## Architecture & Patterns
@@ -49,6 +72,7 @@ Compiler and tooling settings are defined in `tsconfig.json` and `package.json`.
 * Prefer code reuse and refactoring over code duplication
 * Keep utility modules free of `vscode` dependencies where practical; isolate `vscode` access at boundaries
 * Reuse existing readers/parsers/helpers before introducing new abstractions
+* Always consider the larger project context before making a change; prefer refactoring shared code or internal APIs over introducing local workarounds that add complexity
 
 ## Logging & Diagnostics
 
@@ -58,9 +82,9 @@ Compiler and tooling settings are defined in `tsconfig.json` and `package.json`.
 ## Validation & Error Handling
 
 * Validate external inputs at boundaries (especially workspace/debug configuration inputs)
-* Reuse existing parser/reader patterns in the surrounding module
+* Don't add error handling for scenarios that can't happen; only validate at system boundaries
 * Provide meaningful error and log messages that help troubleshooting
-* Preserve existing behavior unless a change is intentional and covered by tests
+* Preserve existing behavior unless a change is intentional; cover behavior changes with tests
 
 ## Imports
 
@@ -70,7 +94,6 @@ Compiler and tooling settings are defined in `tsconfig.json` and `package.json`.
   2. Internal modules
 * Avoid unused imports
 * Use consistent import style across the codebase
-* Follow lint-enforced style: 4-space indentation, single quotes, semicolons
 * Keep `eslint-disable` usage minimal, narrowly scoped, and justified when non-obvious
 
 ## Testing
@@ -80,7 +103,7 @@ Compiler and tooling settings are defined in `tsconfig.json` and `package.json`.
 * Keep tests isolated and deterministic
 * Use descriptive test names
 * Prefer testing behavior over implementation details
-* Prefer code reuse and refactoring over code duplication
+* Extract and generalize shared test logic into helpers or factories when similar patterns appear across tests
 * Follow existing test patterns (`jest.mock`, factory helpers under `src/__test__`, and local feature test factories)
 * Use snapshots when output is structured and stable
 * Keep `any` usage in tests rare; when needed, localize it with explicit lint suppression
@@ -96,16 +119,23 @@ Run the smallest relevant set first, then broaden when touching shared code:
 
 ## General Guidelines
 
-* Follow existing patterns in the codebase
-* Maintain consistency with surrounding code
 * Do not introduce new libraries unless necessary
-* Keep changes minimal and focused
-* If a new source file is completely AI-generated, add `// generated with AI` at the top (per contribution guide)
-* Maintain backward compatibility unless the change intent explicitly requires behavior change
+* Keep changes focused on the task; avoid unrelated changes, but do not shy away from refactoring internal APIs when it leads to a cleaner design
+* Maintain backward compatibility of public APIs unless the change intent explicitly requires it
+
+## Priorities
+
+When guidelines conflict, apply this priority order:
+
+1. Correctness and type safety
+2. Code reuse and clean design (DRY, refactoring over duplication)
+3. Consistency with existing patterns
+4. Minimizing change scope
 
 ## Notes for Copilot
 
-* Always align with existing project structure and patterns
-* When unsure, prioritize consistency over creativity
+* Align with existing project structure and patterns, but flag and fix poor patterns rather than reproducing them
+* When unsure, prioritize correctness and type safety over consistency
 * Ensure all generated code builds, typechecks, and passes tests
 * Prefer existing helpers/factories/utilities over duplicating logic
+* When a fix touches shared or upstream code, prefer improving the shared API over patching around it locally