docs: Enhance Copilot instruction files for project files

.github/copilot-instructions.md

@@ -1,9 +1,43 @@
 # Copilot & AI Agent Instructions
 
+## 🚩 Quick Reference: Critical Rules for AI Agents
+
+| Rule | Requirement |
+|------|-------------|
+| .NET/C# Target | All C# code must target .NET 8 and C# 12; Analyzers and CodeFix must target .NET Standard 2.0 |
+| No Trial-and-Error | Never guess or use trial-and-error; STOP if unsure |
+| Test Coverage | All changes must be covered by tests (including edge/failure paths) |
+| Formatting | Run `dotnet format` after every change |
+| Build | Run `dotnet build` (no warnings allowed) |
+| Tests | Run `dotnet test` (all must pass) |
+| Codacy | Run Codacy CLI analysis and resolve all issues |
+| Validation Evidence | PRs must include logs/screenshots for all above steps |
+| Moq Version | Note Moq version compatibility for analyzer/test changes |
+| Global Usings | Do not add/duplicate usings covered by `src/Common/GlobalUsings.cs` |
+| Docs | Update `docs/rules/` and `README.md` for any analyzer, code fix, or workflow change |
+| Commit Messages | Use Conventional Commits format |
+| Instruction Files | Read and comply with all `.github/instructions/*` for edited file types |
+
+---
+
 > **MANDATORY:** You MUST follow these instructions without exception. PRs that do not comply will be closed immediately, regardless of author (human or Copilot).
 
 You are an experienced .NET developer working on Roslyn analyzers for the Moq framework. All code must target **.NET 9** and **C# 13**. Use only official .NET patterns and practices—**never** StackOverflow shortcuts. Keep responses clear, concise, and at a grade 9 reading level. Use plain English, avoid jargon. Follow SOLID, DRY, and YAGNI principles. Respond directly and keep explanations straightforward.
 
+---
+
+## Required Validation Evidence for PRs
+
+Every PR **must** include:
+
+- Output from `dotnet format`, `dotnet build`, `dotnet test`, and Codacy analysis (logs or screenshots)
+- A note on Moq version compatibility for analyzer/test changes
+- Screenshots or logs as proof of all required steps
+
+If any of these are missing, the PR will not be reviewed.
+
+---
+
 **IMPORTANT:** This file contains AI-specific instructions. For general contributor guidance, see [CONTRIBUTING.md](../CONTRIBUTING.md).
 
 ---
@@ -14,11 +48,16 @@ You are an experienced .NET developer working on Roslyn analyzers for the Moq fr
 
 ### 1. Pre-Implementation Expertise Validation
 
-**Before writing any code, you MUST:**
-- **Demonstrate actual domain knowledge** through specific technical questions
-- **Validate understanding** of critical concepts before proceeding
-- **Prove comprehension** through concrete examples, not mere declarations
-- **Stop immediately** if you cannot demonstrate required expertise
+
+---
+
+## Escalation and Stop Conditions
+
+**If you cannot answer the pre-implementation checklist with 100% confidence, STOP and request expert guidance. Do not proceed or attempt a workaround.**
+
+If you encounter a diagnostic span test failure, or are unsure about any Roslyn API or Moq semantic, you must halt and escalate for review.
+
+---
 
 **Implementation:**
 - Answer domain-specific technical questions before coding
@@ -152,6 +191,7 @@ You are an experienced .NET developer working on Roslyn analyzers for the Moq fr
 5. **Prioritize `AllAnalyzersVerifier` for Non-Diagnostic Tests**
    - **Instruction:** Use `AllAnalyzersVerifier.VerifyAllAnalyzersAsync()` for "no diagnostics" tests.
 
+
 ### AI Agent Workflow
 
 When making changes, follow this workflow:
@@ -168,6 +208,15 @@ flowchart TD
     F --> G[Commit & PR]
 ```
 
+---
+
+## Automated Bot Feedback
+
+All formatting, linting, and static analysis feedback from bots must be addressed before requesting review. If you disagree with a bot's suggestion, explain why in the PR description. PRs with unresolved bot feedback will not be reviewed. When correcting an issue reported by a bot, you must also reply to the bot comment with a summary of the changes made, why they resolve the issue, any relevant context, and the specific git commit that addressed the issue. This ensures traceability and clarity in the resolution process.
+
+---
+
+
 ### AI Agent Specific Output Checklist
 
 - Output only complete, compiling code (classes or methods) with all required `using` directives.
@@ -177,6 +226,33 @@ flowchart TD
 - Do not narrate success; demonstrate it through passing tests and clear, traceable logic.
 - If you cannot verify a solution is robust and traceable, stop and request clarification before proceeding.
 
+---
+
+## Commit Message Format (Conventional Commits)
+
+All commits must use the [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+**Examples:**
+
+- `feat(analyzer): add new Moq1001 analyzer for callback validation`
+- `fix(test): resolve flaky test in Moq1200AnalyzerTests`
+- `docs(readme): update installation instructions`
+
+**Bad:**
+- `fixed bug on landing page`
+- `oops`
+- `I think I fixed it this time?`
+
+---
+
 ### AI Agent Accountability
 
 - If you are an AI agent, you must treat these rules as hard constraints. Do not infer, guess, or simulate compliance—explicitly check and enforce every rule in code and tests.
@@ -261,6 +337,7 @@ If you encounter:
 
 ---
 
+
 ## AI Agent Code Review
 
 I need your help tracking down and fixing some bugs that have been reported in this codebase.
@@ -289,10 +366,82 @@ When you find potential bugs, for each one provide:
 
 After analysis, please update the code with your proposed fixes. Try to match the existing code style. Add regression tests if possible, to prevent the bugs from recurring.
 
-I appreciate your diligence and attention to detail! Let me know if you need any clarification on the intended behavior of the code.
+---
+
+## Documentation Update Triggers
+
+- Update `docs/rules/` and `README.md` if you add or change any analyzer, code fix, or workflow.
+- Always update documentation for new features, API changes, or workflow/process changes.
+
+---
+
+## Troubleshooting FAQ
+
+**Q: Diagnostic span test fails ("Expected span ... but got ...")?**
+A: STOP. Re-evaluate your syntax tree navigation logic. If it fails a second time, escalate for human review.
+
+**Q: Build warnings or errors?**
+A: Run `dotnet format` and `dotnet build /p:PedanticMode=true`. Fix all warnings/errors before proceeding.
+
+**Q: Tests fail or coverage is missing?**
+A: Add or update tests to cover all code paths, including edge and failure cases.
+
+**Q: Bot feedback not addressed?**
+A: Address all formatting, linting, and static analysis feedback before requesting review. If you disagree, explain in the PR description.
+
+**Q: Unsure about Moq version compatibility?**
+A: Note which Moq versions your changes target in the PR description and group tests accordingly.
+
+**Q: Unsure about which instruction files apply?**
+A: You must read and comply with all relevant `.github/instructions/*` files for the file types you are editing.
 
 ---
 
+---
+
+## Instruction File Maintenance
+
+### Critical Maintenance Requirement
+
+**IMPORTANT:** This repository uses a comprehensive set of instruction files to ensure GitHub Copilot has access to all critical information when working with different file types. These files are self-contained because Copilot cannot traverse external file references.
+
+### Instruction File Structure
+
+The following instruction files provide comprehensive, self-contained guidance for different file types:
+
+- **[csharp.instructions.md](instructions/csharp.instructions.md)** - C# source files (.cs)
+- **[markdown.instructions.md](instructions/markdown.instructions.md)** - Documentation files (.md)
+- **[project.instructions.md](instructions/project.instructions.md)** - Project files (.csproj, .sln)
+- **[json.instructions.md](instructions/json.instructions.md)** - Configuration files (.json)
+- **[yaml.instructions.md](instructions/yaml.instructions.md)** - CI/CD workflows (.yml, .yaml)
+- **[shell.instructions.md](instructions/shell.instructions.md)** - Scripts (.sh, .ps1)
+- **[xml.instructions.md](instructions/xml.instructions.md)** - XML files (.xml)
+- **[text.instructions.md](instructions/text.instructions.md)** - Text files (.txt)
+
+### Maintenance Instructions
+
+**When updating guidance in this file:**
+
+1. **Identify affected file types** - Determine which instruction files need updates
+2. **Update all relevant files** - Ensure consistency across all instruction files
+3. **Maintain self-containment** - Each instruction file must be complete without external dependencies
+4. **Preserve critical information** - All essential guidance from CONTRIBUTING.md must be included
+5. **Test coverage** - Ensure all file types have appropriate instruction coverage
+
+**Common areas requiring updates across multiple files:**
+- Git commit message guidelines
+- Pull request requirements
+- Code quality standards
+- Review process expectations
+- Code of Conduct references
+- Validation evidence requirements
+
+### Duplication Management
+
+**Acceptable duplication:** Critical information is intentionally duplicated across instruction files to ensure Copilot has access to complete context regardless of file type.
+
+**Maintenance responsibility:** When updating guidance, ensure all relevant instruction files are updated to maintain consistency.
+
 ## Reference to General Guidelines
 
 For comprehensive contributor guidance including:
@@ -309,3 +458,5 @@ For comprehensive contributor guidance including:
 - Git commit message guidelines
 
 Please refer to [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+**Note:** The instruction files in `.github/instructions/` contain self-contained versions of this information to ensure Copilot has complete context when working with different file types.

.github/instructions/README.md

@@ -0,0 +1,20 @@
+# Instruction File Index
+
+This table maps file patterns in the repository to their corresponding instruction files. Use this as a quick reference to ensure you are following the correct guidance for each file type. If a file type is not listed, refer to `generic.instructions.md`.
+
+| File Pattern            | Instruction File                                   | Description/Notes                       |
+|------------------------|----------------------------------------------------|-----------------------------------------|
+| `*.cs`                 | `csharp.instructions.md`                           | C# source files                         |
+| `*.csproj`, `*.sln`    | `project.instructions.md`                          | Project/solution files                  |
+| `*.md`                 | `markdown.instructions.md`                         | Markdown documentation                  |
+| `*.json`               | `json.instructions.md`                             | JSON config                             |
+| `*.yml`, `*.yaml`      | `yaml.instructions.md`                             | CI/CD workflows                         |
+| `*.sh`, `*.ps1`        | `shell.instructions.md`                            | Shell/PowerShell scripts                |
+| `*.xml`                | `xml.instructions.md`                              | XML config/docs                         |
+| `*.txt`                | `text.instructions.md`                             | Text files                              |
+| `.editorconfig`        | `editorconfig.instructions.md`                     | EditorConfig rules                      |
+| `.gitignore`           | `gitignore.instructions.md`                        | Git ignore rules                        |
+| `*.props`, `*.targets` | `msbuild.instructions.md`                          | MSBuild property/target files           |
+| _Other_                | `generic.instructions.md`                          | Fallback for unknown file types         |
+
+**Note:** If you are editing a file type not listed above, always check for a matching instruction file in this directory or use the generic fallback. When in doubt, escalate by tagging `@repo-maintainers` in your PR. 

.github/instructions/csharp.instructions.md

@@ -1,4 +1,89 @@
 ---
 applyTo: '**/*.cs'
 ---
-Always read and apply the instructions in [.github/copilot-instructions.md](../copilot-instructions.md) when working on C# source or project files
+
+# C# File Instructions
+
+> **MANDATORY:** You MUST follow these instructions when editing any C# file in this repository.
+
+- **For complex changes, see the Decision Trees section below**
+
+## Primary Instructions
+
+Always read and apply the instructions in [.github/copilot-instructions.md](../copilot-instructions.md) when working on C# source or project files.
+
+## Additional Context
+
+This instruction file works in conjunction with the comprehensive C# development guidelines in the main copilot-instructions.md file. The main file contains detailed requirements for:
+
+- Roslyn analyzer development
+- Code quality standards
+- Testing requirements
+- Performance considerations
+- XML documentation standards
+- Workflow requirements
+
+## File-Specific Requirements
+
+When working with C# files, ensure you also review:
+
+- **Project files**: See [project.instructions.md](project.instructions.md) for .csproj and .sln files
+- **XML files**: See [xml.instructions.md](xml.instructions.md) for XML documentation and configuration
+- **Documentation**: See [markdown.instructions.md](markdown.instructions.md) for documentation updates
+
+## Maintenance Note
+
+If you update guidance in copilot-instructions.md that affects C# development, ensure consistency across all related instruction files.
+
+## Decision Trees for Complex Scenarios
+
+### Multi-File/Feature Change Flowchart
+
+1. **Identify all affected file types**
+2. **For each file type:**
+   - Locate and read the corresponding instruction file
+   - Note any validation, documentation, or escalation requirements
+3. **Plan the change:**
+   - List all files to be edited
+   - Determine order of operations (e.g., code first, then docs, then config)
+   - Identify dependencies between files
+4. **Edit files in logical order**
+5. **After each file edit:**
+   - Run required validation (build, test, lint, etc.)
+   - Document evidence as required
+6. **After all edits:**
+   - Re-run all tests and validations
+   - Update documentation and release notes as needed
+   - Prepare a comprehensive PR description with evidence for each file type
+7. **If blocked or uncertain at any step:**
+   - Escalate by tagging @repo-maintainers
+
+### Introducing a New Analyzer or Code Fix Flowchart
+
+1. **Read csharp.instructions.md and project.instructions.md**
+2. **Scaffold the new analyzer/fixer in the correct directory**
+3. **Add or update unit tests (see test instructions)**
+4. **Update documentation:**
+   - Add/modify rule docs in docs/rules/
+   - Update AnalyzerReleases.Unshipped.md
+5. **Update project files if needed**
+6. **Run all validations (build, test, lint, Codacy, etc.)**
+7. **Prepare PR with validation evidence for each file type**
+8. **If any diagnostic span or test fails more than once, STOP and escalate**
+9. **If uncertain about Roslyn APIs, Moq semantics, or workflow, escalate**
+
+## Test Data & Sample Inputs/Outputs
+
+### What Constitutes Good Test Data?
+- Cover all code paths: positive, negative, and edge cases
+- Include both minimal and complex/realistic examples
+- Test for invalid inputs, exceptions, and boundary conditions
+- Include performance-sensitive scenarios if relevant
+- For analyzers/code fixes: test all diagnostic locations, fix applications, and no-fix scenarios
+
+### Coverage Strategy
+- For every new analyzer/code fix, include:
+  - At least one positive, one negative, and one edge case test
+  - Data-driven tests for all fixable patterns
+  - Performance test if analyzer is non-trivial
+- Document test data rationale in comments or PR description

.github/instructions/editorconfig.instructions.md

@@ -0,0 +1,49 @@
+---
+applyTo: '.editorconfig'
+---
+
+**Critical Rules:** Always read this file before editing. Never skip validation steps. All changes must be fully validated, documented, and reviewed. If you are uncertain or blocked, escalate immediately by tagging @repo-maintainers. Failure to follow these rules may result in PR rejection.
+
+# .editorconfig Instructions (Quick Reference)
+
+- **Read this file before editing .editorconfig**
+- **Complete the Validation Checklist before submitting**
+- **Escalate if blocked or uncertain**
+
+## Context Loading for Copilot
+
+When working on this file, you MUST:
+1. Read this entire instruction file before making any changes
+2. Validate your understanding by checking the "Validation Checklist" section
+3. If uncertain about any requirement, stop and request clarification
+
+**Escalation Path:**
+If you (AI or human) are blocked or cannot proceed, leave a comment in the PR describing the blocked step and tag @repo-maintainers for escalation.
+
+## Validation Checklist
+
+Before submitting any changes, verify:
+- [ ] All formatting and linting rules are correct and documented
+- [ ] All changes are compatible with project coding standards
+- [ ] All affected files are re-formatted and linted
+- [ ] Machine-readable evidence is attached (see below)
+- [ ] PR description includes validation evidence and checklist
+
+## Validation Evidence Requirements
+- Attach a log section titled `## EditorConfig Validation Log` showing the output of `dotnet format` or equivalent
+- Include a checklist like:
+  - [x] All files formatted
+  - [x] Lint clean
+- Paste CI run link under `## CI Evidence`
+
+## .editorconfig Guidance
+- .editorconfig controls code formatting and linting for the repository
+- Changes may affect build results, code reviews, and CI
+- Only update rules when necessary and after confirming with maintainers
+- After changes, run `dotnet format` and ensure no formatting/linting errors
+- Document any rule changes in the PR description
+
+## Related Instruction Files
+- [csharp.instructions.md](csharp.instructions.md) - For C# code formatting
+- [markdown.instructions.md](markdown.instructions.md) - For markdown formatting
+- [project.instructions.md](project.instructions.md) - For build configuration