Update project from its own Copier template (v1.44).

Author: emcd

.auxiliary/configuration/claude/agents/python-conformer.md

@@ -1,26 +1,26 @@
 ---
 name: python-conformer
 description: |
-  Use this agent ONLY when changes include Python code (.py and .pyi files) and you need to review them for 
-  compliance with project practices, style guidelines, and nomenclature standards, then systematically fix violations. 
+  Use this agent ONLY when changes include Python code (.py and .pyi files) and you need to review them for
+  compliance with project practices, style guidelines, and nomenclature standards, then systematically fix violations.
   Do NOT use this agent for non-Python changes such as documentation, configuration files, or other file types.
-  
+
   Examples:
-  
+
   <example>
   Context: The user has just written a new Python function and wants to ensure it follows project standards.
   user: 'I just wrote this function for processing user data. Can you review it?'
   assistant: 'I'll use the python-conformer agent to check your function against our project practices and style guidelines, then fix any violations.'
   <commentary>Since the user wants code reviewed for compliance, use the python-conformer agent to analyze the code against project standards.</commentary>
   </example>
-  
+
   <example>
   Context: The user has completed a module refactor and wants to verify compliance before committing.
   user: 'I've finished refactoring the authentication module. Please check if it meets our coding standards.'
   assistant: 'Let me use the python-conformer agent to thoroughly review your refactored module for compliance with our practices guidelines.'
   <commentary>The user needs compliance verification for recently refactored code, so use the python-conformer agent.</commentary>
   </example>
-  
+
   <example>
   Context: The user wants to review staged Python changes before committing.
   user: 'I've modified several Python modules. Please review my staged changes for compliance before I commit.'
@@ -144,7 +144,9 @@ functionality.
 **Unacceptable Suppressions (require investigation):**
 - `type: ignore` MUST NOT be used, except in extremely rare circumstances. Such
   suppressions usually indicate missing third-party dependencies or type stubs,
-  inappropriate type variables, or a bad inheritance pattern.
+  inappropriate type variables, or a bad inheritance pattern. For complex type
+  suppression investigation and dependency management, delegate to the
+  `python-annotator` agent.
 - `__.typx.cast` SHOULD NOT be used, except in extremely rare circumstances.
   Such casts suppress normal type checking and usually the same problems as
   `type: ignore`.
@@ -263,7 +265,7 @@ def _group_documents_by_field(
 
 **Violations identified:**
 1. **Narrow parameter types**: `list[dict[...]]` instead of wide `__.cabc.Sequence[__.cabc.Mapping[...]]`
-2. **Type suppression abuse**: `# type: ignore[arg-type]` masks real design issue
+2. **Type suppression abuse**: `# type: ignore[arg-type]` masks real design issue (delegate to `python-annotator` agent for systematic suppression resolution)
 3. **Mutable container return**: Returns `dict` instead of `__.immut.Dictionary`
 4. **Function body blank lines**: Empty lines breaking vertical compactness
 5. **Vertical compactness**: `return { }` could be same line as `if`
@@ -323,8 +325,6 @@ def _group_documents_by_field(
 ## TOOL PREFERENCES
 
 - **Precise coordinates**: Use `rg --line-number --column` for exact line/column positions
-- **File editing**: Prefer `text-editor` MCP tools for line-based edits to avoid conflicts
-- **File synchronization**: Always reread files with `text-editor` tools after modifications by other tools (like `pyright` or `ruff`)
 - **Batch operations**: Group related changes together to minimize file modification conflicts between different MCP tools
 
 ## EXECUTION REQUIREMENTS
@@ -335,4 +335,5 @@ def _group_documents_by_field(
 - **Focus on compliance**: Maintain exact functionality while improving standards adherence
 - **Reference specific lines**: Always include line numbers and concrete examples
 - **Document reasoning**: Explain why each standard matters and how fixes align with project practices
+- **Agent delegation**: When type annotation issues exceed basic compliance scope, consider delegating to the `python-annotator` agent for comprehensive type work
 - **Guide access**: If any prerequisite guide cannot be accessed, stop and inform the user

.auxiliary/configuration/claude/commands/cs-annotate-release.md

@@ -12,7 +12,7 @@ You are tasked with creating Towncrier news fragments for user-facing changes
 since the last release cleanup. This command analyzes recent commits and
 generates appropriate changelog entries.
 
-Special instructions: `$ARGUMENTS`
+Special instructions: $ARGUMENTS
 (If above line is empty, then no special instructions were given by the user.)
 
 ## Context

.auxiliary/configuration/claude/commands/cs-code-python.md

@@ -1,5 +1,5 @@
 ---
-allowed-tools: [Read, Write, Edit, MultiEdit, LS, Glob, Grep, Bash, TodoWrite, mcp__text-editor__get_text_file_contents, mcp__text-editor__edit_text_file_contents, mcp__ruff__diagnostics, mcp__ruff__edit_file, mcp__ruff__hover, mcp__ruff__references, mcp__ruff__rename_symbol, mcp__ruff__definition, mcp__pyright__diagnostics, mcp__pyright__edit_file, mcp__pyright__hover, mcp__pyright__references, mcp__pyright__rename_symbol, mcp__pyright__definition, mcp__context7__resolve-library-id, mcp__context7__get-library-docs]
+allowed-tools: [Read, Write, Edit, MultiEdit, LS, Glob, Grep, Bash, TodoWrite, mcp__ruff__diagnostics, mcp__ruff__edit_file, mcp__ruff__hover, mcp__ruff__references, mcp__ruff__rename_symbol, mcp__ruff__definition, mcp__pyright__diagnostics, mcp__pyright__edit_file, mcp__pyright__hover, mcp__pyright__references, mcp__pyright__rename_symbol, mcp__pyright__definition, mcp__context7__resolve-library-id, mcp__context7__get-library-docs]
 description: Python implementation following established patterns and practices
 ---
 
@@ -33,11 +33,12 @@ Before implementing Python code, ensure:
 ## Process Summary
 
 Key functional areas:
-1. **Requirements Analysis**: Understand implementation requirements and context
-2. **Design Conformance**: Ensure alignment with established patterns and practices
+1. **Requirements Analysis**: Understand implementation requirements and create persistent tracking
+2. **Session Continuity**: Check for existing work and preserve context across sessions
 3. **Implementation**: Write Python code following style guidelines and best practices
-4. **Quality Assurance**: Run linters, type checkers, and tests to validate code
-5. **Documentation**: Provide implementation summary and any necessary documentation
+4. **Progress Tracking**: Maintain session and cross-session implementation progress
+5. **Quality Assurance**: Run linters, type checkers, and tests to validate code
+6. **Documentation**: Update persistent tracking and provide implementation summary
 
 ## Safety Requirements
 
@@ -63,15 +64,87 @@ Analyze implementation requirements and gather context:
 - Understand expected behavior and edge cases
 - Document implementation scope and constraints
 
-### 2. Design Conformance Checklist
-Ensure implementation aligns with project standards:
-- [ ] Module organization follows practices guidelines (imports → type aliases → defaults → public API → private functions)
+#### 1.1 Create Implementation Tracking File
+Before beginning implementation, create a persistent tracking file with descriptive naming:
+- Format: `.auxiliary/notes/<short-implementation-title>--progress.md`
+- Example: `.auxiliary/notes/user-metrics-export--progress.md`
+
+Choose a concise but descriptive title that captures the main implementation goal.
+
+Structure the tracking file with these sections:
+
+### Context and References
+- **Implementation Title**: [Brief description of what is being implemented]
+- **Start Date**: [YYYY-MM-DD]
+- **Reference Files**: [List all files explicitly provided as context/references at start]
+  - `path/to/reference1.py` - [Brief description of relevance]
+  - `path/to/reference2.rst` - [Brief description of relevance]
+- **Design Documents**: [Any architecture or design docs referenced]
+- **Session Notes**: [Link to current session TodoWrite items]
+
+### Design and Style Conformance Checklist
+- [ ] Module organization follows practices guidelines
 - [ ] Function signatures use wide parameter, narrow return patterns
-- [ ] Type annotations are comprehensive and use proper TypeAlias patterns
+- [ ] Type annotations comprehensive with TypeAlias patterns
 - [ ] Exception handling follows Omniexception → Omnierror hierarchy
-- [ ] Naming follows nomenclature conventions with appropriate linguistic consistency
-- [ ] Immutability preferences are applied where appropriate
-- [ ] Code style follows spacing, vertical compactness, and formatting guidelines
+- [ ] Naming follows nomenclature conventions
+- [ ] Immutability preferences applied
+- [ ] Code style follows formatting guidelines
+
+### Implementation Progress Checklist
+- [ ] [Specific function/class/module 1]
+- [ ] [Specific function/class/module 2]
+- [ ] [Integration point 1] tested
+- [ ] [Integration point 2] tested
+
+### Quality Gates Checklist
+- [ ] Linters pass (`hatch --env develop run linters`)
+- [ ] Type checker passes
+- [ ] Tests pass (`hatch --env develop run testers`)
+- [ ] Code review ready
+
+### Decision Log
+Document significant decisions made during implementation:
+- [Date] [Decision made] - [Rationale]
+- [Date] [Trade-off chosen] - [Why this approach over alternatives]
+
+### Handoff Notes
+For future sessions or other developers:
+- **Current State**: [What's implemented and what's not]
+- **Next Steps**: [Immediate next actions needed]
+- **Known Issues**: [Any problems or concerns to address]
+- **Context Dependencies**: [Critical knowledge for continuing work]
+
+### 2. Session Continuity and Context Preservation
+Before proceeding with implementation:
+
+#### Check for Existing Implementation
+```bash
+ls .auxiliary/notes/*--progress.md
+```
+
+If continuing previous work:
+- Read existing tracking file completely to understand context
+- Review reference files listed in context section
+- Check decision log for previous design choices
+- Update "Current State" in handoff notes as you resume work
+
+#### Context Preservation Requirements
+Before beginning implementation:
+- [ ] Create descriptive tracking file (`.auxiliary/notes/<title>--progress.md`)
+- [ ] Record all reference files provided at session start
+- [ ] Document initial understanding of requirements
+- [ ] Note any existing related implementations or patterns found
+
+During implementation:
+- [ ] Update decision log when making design choices
+- [ ] Record integration points and dependencies discovered
+- [ ] Document deviations from original plan with rationale
+
+Before session end:
+- [ ] Update current state in handoff notes
+- [ ] Ensure TodoWrite completions are reflected in persistent tracking where granularity aligns
+- [ ] Record next steps for continuation
 
 ### 3. Implementation
 Write Python code following established patterns:
@@ -83,13 +156,14 @@ Write Python code following established patterns:
 - Apply nomenclature patterns for consistent naming
 - Ensure functions are ≤30 lines and modules are ≤600 lines
 
-### 4. Implementation Tracking Checklist
-Track progress against requirements:
-- [ ] All specified functions/classes have been implemented
-- [ ] Required functionality is complete and tested
-- [ ] Integration points with existing code are working
-- [ ] Edge cases and error conditions are handled
-- [ ] Documentation requirements are satisfied
+For complex type annotation issues or when adding comprehensive type annotations to existing code, consider using the `python-annotator` agent.
+
+### 4. Progress Tracking Requirements
+Maintain dual tracking systems:
+- **Session Level**: Use TodoWrite tool for immediate task management within current session
+- **Cross-Session**: Update `.auxiliary/notes/<implementation-title>--progress.md` for persistent tracking
+- **Synchronization**: When TodoWrite items align with persistent checklist granularity, update corresponding persistent checklist items (TodoWrite may be more fine-grained)
+- **Context Preservation**: Record all reference files and design decisions in persistent file for future session continuity
 
 ### 5. Quality Assurance
 Validate code quality and conformance following zero-tolerance policy:
@@ -114,6 +188,7 @@ Type Error Resolution Process:
    - Generate stubs: `hatch --env develop run pyright --createsub <package>`
    - Complete necessary stub definitions
    - Re-run type checker to verify resolution
+3. Complex Type Issues: For comprehensive type annotation work, systematic suppression resolution, or complex dependency management, consider using the `python-annotator` agent.
 
 Stop and consult user if:
 - Type errors cannot be categorized as code issues or third-party stub gaps
@@ -128,8 +203,10 @@ Ensure all tests pass, including any new tests created.
 
 ### 6. Documentation and Summary
 Provide implementation documentation:
-- Document any non-obvious design decisions or trade-offs
+- Update persistent tracking file with final implementation state
+- Document any non-obvious design decisions or trade-offs in decision log
 - Create or update relevant docstrings following narrative mood guidelines
+- Complete handoff notes with current state and next steps
 - Note any TODO items for future enhancements
 - Verify alignment with filesystem organization patterns
 

.auxiliary/configuration/claude/commands/cs-conform-python.md

@@ -7,7 +7,7 @@ description: Systematically conform Python code to project style and practice st
 
 For bringing existing Python code into full compliance with project standards.
 
-Target code: `$ARGUMENTS`
+Target: $ARGUMENTS
 
 Focus on style/practice conformance, not functionality changes.
 
@@ -121,7 +121,9 @@ Acceptable Suppressions:
 Unacceptable Suppressions (require investigation):
 - `type: ignore` MUST NOT be used, except in extremely rare circumstances. Such
   suppressions usually indicate missing third-party dependencies or type stubs,
-  inappropriate type variables, or a bad inheritance pattern.
+  inappropriate type variables, or a bad inheritance pattern. For systematic
+  investigation and resolution of type suppressions, consider using the
+  `python-annotator` agent.
 - `__.typx.cast` SHOULD NOT be used, except in extremely rare circumstances.
   Such casts suppress normal type checking and usually the same problems as
   `type: ignore`.
@@ -297,17 +299,10 @@ Phase 2 Output:
 3. **Files Modified**: Complete list with brief description of changes
 4. **Manual Review Required**: Any issues requiring human judgment
 
-## Tool Preferences
-
-- **Precise coordinates**: Use `rg --line-number --column` for exact line/column positions
-- **File editing**: Prefer `text-editor` MCP tools for line-based edits to avoid conflicts
-- **File synchronization**: Always reread files with `text-editor` tools after modifications by other tools (like `pyright` or `ruff`)
-- **Batch operations**: Group related changes together to minimize file modification conflicts between different MCP tools
-
 ## Conformance Process
 
 ### 1. Analysis Phase (PHASE 1)
-- Examine target files to understand current state  
+- Examine target files to understand current state
 - Run linters to identify specific violations
 - Identify architectural patterns that need updating
 - Generate comprehensive compliance report
@@ -319,14 +314,14 @@ Apply fixes in systematic order:
 1. **Module Organization**: Reorder imports, type aliases, functions per practices guide
 2. **Wide/Narrow Types**: Convert function parameters to wide abstract types
 3. **Import Cleanup**: Remove namespace pollution, use private aliases and __ subpackage
-4. **Type Annotations**: Add missing hints, create `TypeAlias` for complex types
+4. **Type Annotations**: Add missing hints, create `TypeAlias` for complex types. For comprehensive type annotation work or complex type checking issues, consider using the `python-annotator` agent.
 5. **Exception Handling**: Narrow try block scope, ensure proper chaining
 6. **Immutability**: Replace mutable with immutable containers where appropriate
 7. **Spacing/Delimiters**: Fix `( )`, `[ ]`, `{ }` patterns
 8. **Docstrings**: Triple single quotes, narrative mood, proper spacing
 9. **Line Length**: Split at 79 columns using parentheses
 
-**Requirements**: 
+**Requirements**:
 - Maintain exact functionality while improving standards adherence
 - Validate with `hatch --env develop run linters` (must produce clean output)
 - Run `hatch --env develop run testers` to ensure no functionality breaks

.auxiliary/configuration/claude/commands/cs-conform-toml.md

@@ -7,7 +7,7 @@ description: Systematically conform TOML files to project style and practice sta
 
 For bringing existing TOML configuration files into full compliance with project standards.
 
-Target files: `$ARGUMENTS`
+Target files: $ARGUMENTS
 
 Focus on style/practice conformance, not functionality changes.
 

.auxiliary/configuration/claude/commands/cs-develop-pytests.md

@@ -15,7 +15,6 @@ Implement tests according to the provided test plan only.
 
 - Current git status: !`git status --porcelain`
 - Current branch: !`git branch --show-current`
-- Test plan to implement: !`ls "$ARGUMENTS" 2>/dev/null && echo "Present" || echo "Missing"`
 - Existing test structure: !`find tests -name "*.py" | head -20`
 - Test organization: @documentation/architecture/testplans/summary.rst
 - Test plans index: @documentation/architecture/testplans/index.rst
@@ -66,6 +65,8 @@ Stop and consult the user if:
 
 **Your responsibilities:**
 - Follow the test plan precisely while adhering to project conventions
+- Focus only on uncovered areas specified in the plan
+- Avoid redundant testing of functionality already covered by doctests
 - Use dependency injection patterns as specified in the plan
 - Implement tests exactly as planned without adding extras
 - Maintain systematic test numbering as outlined in the plan
@@ -74,8 +75,6 @@ Stop and consult the user if:
 
 ## Test Implementation Process
 
-Execute the following steps for test plan: `$ARGUMENTS`
-
 ### 0. Pre-Flight Verification
 Verify access to project guidelines:
 
@@ -89,11 +88,6 @@ You must successfully access and read all three guides before proceeding. If any
 ### 1. Test Plan Reading and Validation
 Read and validate the provided test plan:
 
-Read the test plan document at the provided path:
-```
-Read the test plan file at: $ARGUMENTS
-```
-
 **Validate plan completeness:**
 - Verify plan contains coverage analysis summary
 - Confirm test strategy is clearly defined
@@ -118,7 +112,25 @@ Stop if the plan is incomplete, unclear, or missing critical sections.
 - Ensure no duplication of existing test coverage
 
 ### 3. Test Data and Fixture Setup
-**Prepare test data as specified in the plan:**
+**Prepare test data and dependencies as specified in the plan:**
+
+**Ensure required test dependencies are available:**
+If the test plan requires dependencies not in the current environment, add them to `pyproject.toml`:
+
+```toml
+[tool.hatch.envs.develop]
+dependencies = [
+    # ... existing dependencies
+    "pyfakefs",       # For filesystem mocking
+    "pytest-asyncio", # For async test support
+    # ... other test-specific dependencies in alphabetical order
+]
+```
+
+After adding dependencies, rebuild the environment to ensure consistency:
+```bash
+hatch env prune
+```
 
 **Create required test data under tests/data/:**
 - Set up fake packages for extension mechanisms (if planned)
@@ -175,6 +187,18 @@ hatch --env develop run linters
 
 ## Test Pattern Examples
 
+**Import Patterns:**
+
+*Direct imports (preferred for most cases):*
+```python
+from mypackage import mymodule
+
+def test_100_basic_functionality( ):
+    ''' Module function works correctly with valid input. '''
+    result = mymodule.process_data( 'test' )
+    assert result == 'processed: test'
+```
+
 **Dependency Injection Pattern:**
 ```python
 async def test_100_process_with_custom_processor( ):

.auxiliary/configuration/claude/commands/cs-inquire.md

@@ -9,7 +9,7 @@ Provide analytical responses, technical opinions, and architectural discussion
 based on user questions. Focus on analysis and reasoning without making code
 modifications.
 
-User question or topic: `$ARGUMENTS`
+User question or topic: $ARGUMENTS
 
 Stop and consult if:
 - The request explicitly asks for code changes or implementation