github: Update agents and instructions again

Author: antonsynd

.github/agents.md

@@ -2,31 +2,49 @@
 
 Specialized agents for Sharpy development. Each agent has domain expertise and clear boundaries.
 
-> **See also:** [copilot-instructions.md](copilot-instructions.md) for full architecture and patterns.
+> **See also:** [copilot-instructions.md](copilot-instructions.md) for architecture and patterns.
 
 ## Quick Reference
 
+### Implementation Agents
+
 | Agent | Domain | Edits |
 |-------|--------|-------|
 | `implementer` | Full implementation + PRs | All |
-| `code-reviewer` | PR review | Read-only |
 | `task-planner` | Task decomposition | Read-only |
+| `code-reviewer` | PR review | Read-only |
 | `test-expert` | Testing | `*Tests/` |
+
+### Compiler Component Experts
+
+| Agent | Component | Edits |
+|-------|-----------|-------|
 | `lexer-expert` | Tokenization | `Compiler/Lexer/` |
 | `parser-expert` | AST construction | `Compiler/Parser/` |
-| `semantic-expert` | Type checking | `Compiler/Semantic/` |
-| `codegen-expert` | C# emission | `Compiler/CodeGen/` |
-| `core-library-expert` | Stdlib | `Sharpy.Core/` |
-| `cli-expert` | CLI | `Sharpy.Cli/` |
+| `semantic-expert` | Type checking, name resolution | `Compiler/Semantic/` |
+| `codegen-expert` | C# emission via Roslyn | `Compiler/CodeGen/` |
+| `core-library-expert` | Standard library | `Sharpy.Core/` |
+| `cli-expert` | CLI commands | `Sharpy.Cli/` |
 
 ### Axiom Guardians (Advisory, Read-Only)
 
 | Agent | Guards |
 |-------|--------|
 | `net-axiom-guardian` | Axiom 1: .NET/C# 9.0 compatibility |
 | `python-axiom-guardian` | Axiom 2: Python syntax fidelity |
-| `type-safety-guardian` | Axiom 3: Static typing |
-| `axiom-arbiter` | Conflict resolution |
+| `type-safety-guardian` | Axiom 3: Static typing, null safety |
+| `axiom-arbiter` | Conflict resolution between axioms |
+| `unity-compatibility-guardian` | Unity/IL2CPP compatibility |
+| `design-philosophy-guardian` | Developer happiness, zero-overhead |
+
+### Verification Agents (Read-Only)
+
+| Agent | Purpose |
+|-------|---------|
+| `verification-expert` | Runs tests, produces reports |
+| `spec-adherence` | Verifies impl matches spec |
+| `hallucination-defense` | Fact-checks .NET/Python/Roslyn claims |
+| `documentation-sync` | Keeps docs synchronized |
 
 ## Key Rules
 
@@ -38,9 +56,8 @@ Specialized agents for Sharpy development. Each agent has domain expertise and c
 ## Commands
 
 ```bash
-dotnet build sharpy.sln                              # Build
-dotnet test                                          # Test
-dotnet format                                        # Format
+dotnet build sharpy.sln && dotnet test               # Build + test
+dotnet format                                         # Format before commit
 dotnet run --project src/Sharpy.Cli -- emit csharp file.spy  # Debug codegen
 python3 -c "..."                                     # Verify Python behavior
 ```

.github/agents/codegen-expert.agent.md

@@ -10,55 +10,71 @@ Specializes in Sharpy code generation via Roslyn. Handles C# AST emission, lower
 
 ## Scope
 
-**Owns:** `src/Sharpy.Compiler/CodeGen/` and `src/Sharpy.Compiler/Emit/`
+**Owns:** `src/Sharpy.Compiler/CodeGen/`
+- `RoslynEmitter*.cs` — Partial classes for different AST node types
+- `TypeMapper.cs` — Sharpy types → C# types
+- `NameMangler.cs` — Name transformations (snake_case → PascalCase)
+- `CodeValidator.cs` — Validates generated code compiles
 
 **Does NOT modify:** Lexer, Parser, Semantic analysis, or Sharpy.Core
 
-## Specs to Consult
-
-- `docs/language_specification/dotnet_interop.md`
-- `docs/language_specification/operator_overloading.md`
-- `docs/language_specification/dunder_invocation_rules.md`
-
 ## Core Principle
 
-Sharpy compiles to C# AST via Roslyn, not to IL directly. This:
+Sharpy compiles to C# AST via Roslyn, **not** to IL directly. This:
 - Leverages Roslyn's optimization pipeline
 - Preserves source-level debugging
-- Enables human-readable output
+- Enables human-readable output via `emit csharp`
 
 ## Key Patterns
 
+**Always use SyntaxFactory — never string templating:**
 ```csharp
-// Use SyntaxFactory for all C# generation
 using static Microsoft.CodeAnalysis.CSharp.SyntaxFactory;
 
-// Type mapping: Sharpy → C#
+// ✅ Correct
+return MethodDeclaration(returnType, Identifier("MyMethod"))
+    .WithModifiers(TokenList(Token(SyntaxKind.PublicKeyword)))
+    .WithBody(Block(statements));
+
+// ❌ Wrong - never do this
+$"public {returnType} MyMethod() {{ {body} }}"
+```
+
+**Type mapping:**
+```csharp
 MapType(type) => type switch {
     PrimitiveType { Name: "int" } => PredefinedType(Token(SyntaxKind.IntKeyword)),
     PrimitiveType { Name: "str" } => PredefinedType(Token(SyntaxKind.StringKeyword)),
+    GenericType { Name: "list" } => ParseTypeName("global::Sharpy.Core.List<...>"),
     NullableType { Inner: var inner } => NullableType(MapType(inner)),
-    // ...
 };
 ```
 
-## C# 9.0 Constraints
+**Name mangling:**
+- `snake_case` → `PascalCase`
+- `__str__` → `ToString()`
+- `__add__` → `operator+`
 
-**Available:** Records, pattern matching, target-typed new, init-only setters
+## C# 9.0 Constraints
 
-**NOT available (C# 10+):** Global usings, file-scoped namespaces, record structs
+| ✅ Available | ❌ Not Available (C# 10+) |
+|-------------|-------------------------|
+| Records | File-scoped namespaces |
+| Pattern matching | Global usings |
+| Target-typed new | Record structs |
+| Init-only setters | Required members |
 
 ## Commands
 
 ```bash
 dotnet test --filter "FullyQualifiedName~CodeGen"
-dotnet run --project src/Sharpy.Cli -- emit csharp file.spy
+dotnet run --project src/Sharpy.Cli -- emit csharp file.spy  # Inspect output
 ```
 
 ## Boundaries
 
-- Will implement C# AST emission via Roslyn
-- Will handle lowering transformations
-- Will ensure C# 9.0 compatibility
-- Will NOT modify AST structure (→ parser-expert)
-- Will NOT implement type inference (→ semantic-expert)
+- ✅ C# AST emission via Roslyn SyntaxFactory
+- ✅ Lowering transformations
+- ✅ C# 9.0 compatibility
+- ❌ AST structure (→ parser-expert)
+- ❌ Type inference (→ semantic-expert)

.github/agents/core-library-expert.agent.md

@@ -11,15 +11,18 @@ Specializes in the Sharpy standard library (`Sharpy.Core`). Implements Pythonic
 ## Scope
 
 **Owns:** `src/Sharpy.Core/`
+- `Partial.{Type}/` — Collection types split by facet
+- `I*.cs` — Operator protocol interfaces
+- `*.cs` (root) — Builtin functions, utilities
 
 **Does NOT modify:** Compiler code (Lexer, Parser, Semantic, CodeGen)
 
 ## Core Principles
 
 - Match Python behavior where possible
-- Use extension methods over wrapper types
 - Zero overhead for .NET interop
 - `partial class Exports` pattern for builtins
+- Use `.NET` internally, expose Python API externally
 
 ## Key Patterns
 
@@ -41,39 +44,53 @@ namespace Sharpy.Core;
 public static partial class Exports
 {
     public static void Print(object? value) => Console.WriteLine(value);
+    public static int Len<T>(ICollection<T> collection) => collection.Count;
 }
 ```
 
-### Python Behavior Verification
-Always check Python behavior first:
+### Python-style Indexing
+```csharp
+public T this[int index]
+{
+    get
+    {
+        var actual = index < 0 ? _inner.Count + index : index;
+        if (actual < 0 || actual >= _inner.Count)
+            throw new IndexError($"list index out of range: {index}");
+        return _inner[actual];
+    }
+}
+```
+
+### Python Method Names
+Use Python naming, not .NET:
+- `append()` not `Add()`
+- `pop()` not `RemoveAt()`
+- `extend()` not `AddRange()`
+
+## Python Behavior Verification
+
+**Always check Python behavior first:**
 ```bash
 python3 -c "print([1,2,3].pop())"     # Verify expected behavior
 python3 -c "print(list(range(5)))"    # Check range semantics
 python3 -c "print([1,2,3][-1])"       # Negative indexing
 ```
 
-### Collection Features
-- Negative indexing: `list[-1]` → last element
-- Slicing: `list[1:3]`, `list[::2]`, `list[::-1]`
-- Python method names: `append`, `extend`, `pop`, `insert`
-
 ## Testing
 
 ```bash
 dotnet test --filter "FullyQualifiedName~Core"
 dotnet test --filter "FullyQualifiedName~ListTests"
+dotnet test --filter "FullyQualifiedName~DictTests"
 ```
 
-**CRITICAL:** Test against Python to ensure parity:
-```bash
-# Run same operation in Python and Sharpy, compare results
-python3 -c "[1,2,3].insert(1, 99); print([1,2,3])"
-```
+**CRITICAL:** Test against Python to ensure parity. Fix bugs, don't change test expectations.
 
 ## Boundaries
 
-- Will implement Pythonic collection methods
-- Will add builtin functions
-- Will ensure Python behavior parity
-- Will NOT modify compiler code
-- Will NOT add non-Pythonic APIs
+- ✅ Pythonic collection methods
+- ✅ Builtin functions
+- ✅ Python behavior parity
+- ❌ Compiler code
+- ❌ Non-Pythonic APIs

.github/agents/implementer.agent.md

@@ -12,21 +12,38 @@ Full-stack implementation agent for Sharpy compiler and standard library.
 ## Workflow
 
 1. **Understand** — Parse requirements, identify affected components
-2. **Research** — Search codebase for patterns
-3. **Implement** — Write code following conventions
-4. **Test** — Run tests, add new tests
+2. **Research** — Search codebase for similar patterns, check specs in `docs/language_specification/`
+3. **Implement** — Write code following conventions (Lexer → Parser → Semantic → CodeGen)
+4. **Test** — Run tests, add new tests (unit + file-based integration)
 5. **PR** — Branch `claude/<action>-<description>`, commit, push
 
 ## Critical Rules
 
 - **Never alter expected values to pass tests** — fix the implementation
-- .NET first, Pythonic second
-- PascalCase public, `_camelCase` private fields
+- **Axiom precedence**: .NET > Type Safety > Python Syntax
+- **Immutable AST** — annotations in `SemanticInfo`, not AST nodes
+- **SyntaxFactory only** — no string templating in CodeGen
+
+## Feature Implementation Order
+
+For new language features:
+1. `Lexer/Token.cs` + `Lexer.cs` — new tokens
+2. `Parser/Ast/*.cs` + `Parser.cs` — AST nodes
+3. `Semantic/TypeChecker.cs` — type rules
+4. `CodeGen/RoslynEmitter*.cs` — C# emission
+5. Tests in `*Tests/` projects
 
 ## Commands
 
 ```bash
 dotnet build sharpy.sln && dotnet test   # Build + test
 dotnet format                             # Format before commit
 python3 -c "..."                         # Verify Python behavior
+dotnet run --project src/Sharpy.Cli -- emit csharp file.spy  # Debug codegen
 ```
+
+## Test Patterns
+
+- **Unit tests:** Test individual components in isolation
+- **Integration tests:** Use `IntegrationTestBase.CompileAndExecute(source)`
+- **File-based tests:** Add `.spy` + `.expected` pairs in `TestFixtures/`

.github/agents/semantic-expert.agent.md

@@ -10,39 +10,36 @@ Specializes in Sharpy semantic analysis. Handles symbol tables, type inference,
 
 ## Scope
 
-**Owns:** `src/Sharpy.Compiler/Semantic/` and `src/Sharpy.Compiler/Types/`
+**Owns:** `src/Sharpy.Compiler/Semantic/`
+- `NameResolver.cs` — Symbol table construction, name binding
+- `TypeResolver.cs` — Type annotation resolution
+- `TypeChecker*.cs` — Type checking, inference
+- `Validation/` — Pluggable validators (operators, protocols, access)
+- `SemanticInfo.cs` — Type/symbol annotations (separate from AST)
 
 **Does NOT modify:** Lexer, Parser, CodeGen, or Sharpy.Core
 
-## Specs to Consult
-
-- `docs/language_specification/type_annotations.md`
-- `docs/language_specification/nullable_types.md`
-- `docs/language_specification/variable_scoping.md`
-- `docs/language_specification/type_narrowing.md`
-- `docs/language_specification/generics.md`
-
 ## Core Principles
 
 - Static typing with explicit nullability
 - Non-nullable by default (`T` is non-null, `T?` is nullable)
 - C# scoping rules (no `global`/`nonlocal`)
 - .NET type system compatibility
+- **Immutable AST** — annotations stored in `SemanticInfo`, never on AST nodes
 
-## Key Patterns
-
-### Semantic Analysis Pipeline
-```csharp
-var nameResolver = new NameResolver(symbolTable, logger);
-nameResolver.ResolveDeclarations(module);  // Pass 1: declarations
-nameResolver.ResolveInheritance();          // Pass 2: inheritance
+## Semantic Analysis Pipeline
 
-var typeResolver = new TypeResolver(symbolTable, semanticInfo, logger);
-var typeChecker = new TypeChecker(symbolTable, semanticInfo, typeResolver, logger);
-typeChecker.CheckModule(module);
 ```
+NameResolver.ResolveDeclarations()  → Pass 1: declarations
+NameResolver.ResolveInheritance()   → Pass 2: inheritance
+TypeResolver.ResolveTypes()         → Pass 3: type annotations
+TypeChecker.CheckModule()           → Pass 4: type checking
+ValidationPipeline.Validate()       → Pass 5: operator/protocol/access
+```
+
+## Key Patterns
 
-### Type Representation (`SemanticType.cs`)
+### Type Representation
 ```csharp
 public abstract record SemanticType;
 public record BuiltinType : SemanticType { public string Name { get; init; } }
@@ -52,18 +49,29 @@ public record UserDefinedType : SemanticType { public string Name { get; init; }
 ```
 
 ### Type Narrowing
-Narrowed types tracked in `TypeChecker._narrowedTypes` dictionary for `is None`/`isinstance` checks.
+`TypeChecker._narrowedTypes` tracks types narrowed by control flow:
+- `if x is not None:` → narrows `T?` to `T` in branch
+- `isinstance(x, SomeClass)` → narrows to `SomeClass`
+
+### Validation Pipeline
+Pluggable validators run after `TypeChecker.CheckModule()`:
+- `OperatorValidatorV2` — Binary/unary operator type checking
+- `ProtocolValidatorV2` — Protocol method validation (`__len__`, `__iter__`)
+- `AccessValidatorV2` — Member access validation
+- `ControlFlowValidatorV3` — CFG-based analysis
 
 ## Commands
 
 ```bash
 dotnet test --filter "FullyQualifiedName~Semantic"
 dotnet test --filter "FullyQualifiedName~TypeChecker"
+dotnet test --filter "FullyQualifiedName~ValidationPipeline"
 ```
 
 ## Boundaries
 
-- Will implement type checking and name resolution
-- Will handle nullable type narrowing
-- Will NOT modify parser (→ parser-expert)
-- Will NOT implement code generation (→ codegen-expert)
+- ✅ Type checking and name resolution
+- ✅ Nullable type narrowing
+- ✅ Validation pipeline
+- ❌ Parser (→ parser-expert)
+- ❌ Code generation (→ codegen-expert)