[v0.8.0.dev2] Adapter validation fix, pre-commit infrastructure, and test modernization

.augmentignore

@@ -1 +1 @@
-__reports__/
+__reports__/

.commitlintrc.json

@@ -6,7 +6,7 @@
       "always",
       [
         "build",
-        "chore", 
+        "chore",
         "ci",
         "docs",
         "feat",

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -48,7 +48,7 @@ body:
       placeholder: |
         - OS: (e.g., Ubuntu 22.04, macOS 14.1, Windows 11)
         - Hatch version: (run `pip show hatch`)
-        - Python version: 
+        - Python version:
         - Package manager: (conda/mamba version if applicable)
         - Current environment: (run `hatch env current`)
       render: markdown
@@ -117,18 +117,18 @@ body:
         Please run the diagnostic commands from the troubleshooting guide and paste the output:
       placeholder: |
         Run these commands and paste the output:
-        
+
         hatch env list
-        hatch env current  
+        hatch env current
         hatch package list
         pip show hatch
-        
+
         For environment-specific issues:
         hatch env python info --hatch_env <env-name> --detailed
-        
+
         For registry issues:
         hatch package add <package-name> --refresh-registry
-        
+
         Cache information:
         ls -la ~/.hatch/cache/packages (Linux/macOS)
         Get-ChildItem -Path $env:USERPROFILE\.hatch\cache (Windows PowerShell)

.github/ISSUE_TEMPLATE/documentation.yml

@@ -46,7 +46,7 @@ body:
       label: Documentation Location
       description: Where is the documentation issue located?
       placeholder: |
-        e.g., README.md, docs/articles/users/CLIReference.md, 
+        e.g., README.md, docs/articles/users/CLIReference.md,
         docs/articles/users/GettingStarted.md, https://crackingshells.github.io/Hatch/
     validations:
       required: true

.github/ISSUE_TEMPLATE/environment_issue.yml

@@ -56,7 +56,7 @@ body:
       placeholder: |
         - OS: (e.g., Ubuntu 22.04, macOS 14.1, Windows 11)
         - Hatch version: (run `pip show hatch`)
-        - Python version: 
+        - Python version:
         - Conda/Mamba version: (run `conda --version` or `mamba --version`)
         - Available disk space: (run `df -h` on Linux/macOS or check disk space on Windows)
       render: markdown
@@ -95,11 +95,11 @@ body:
         Please provide current environment information
       placeholder: |
         Run these commands and paste the output:
-        
+
         hatch env list
         hatch env current
         hatch env python info --hatch_env <env-name> --detailed
-        
+
         For Python environment issues:
         conda env list (or mamba env list)
         conda info (or mamba info)
@@ -151,11 +151,11 @@ body:
         If relevant, provide information about the environment directory structure
       placeholder: |
         Environment directory location: ~/.hatch/envs/<env-name>
-        
+
         Directory contents:
         ls -la ~/.hatch/envs/<env-name>/ (Linux/macOS)
         Get-ChildItem ~/.hatch/envs/<env-name>/ (Windows PowerShell)
-        
+
         Python environment location (if applicable):
         conda env list | grep <env-name>
       render: text
@@ -169,7 +169,7 @@ body:
       placeholder: |
         Run and paste output:
         hatch package list --env <env-name>
-        
+
         For Python environment:
         conda list -n <python-env-name> (or mamba list)
       render: text

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -84,11 +84,11 @@ body:
         If this feature involves new CLI commands, describe the proposed command structure
       placeholder: |
         Propose the command syntax and options:
-        
+
         hatch package search <query> --filter <type>
         hatch env clone <source-env> <target-env>
         hatch template list --category <category>
-        
+
         Include:
         - Command names and subcommands
         - Required and optional arguments
@@ -121,7 +121,7 @@ body:
     attributes:
       label: Implementation Ideas
       description: |
-        Do you have any ideas about how this could be implemented? 
+        Do you have any ideas about how this could be implemented?
         (Optional - only if you have technical insights)
       placeholder: |
         If you have ideas about implementation approaches, technical details, or architecture:

.github/ISSUE_TEMPLATE/package_issue.yml

@@ -137,7 +137,7 @@ body:
           ...
         }
         ```
-        
+
         For validation issues, also include the validation output:
         hatch validate <package-dir>
       render: markdown

.github/workflows/prerelease-discord-notification.yml

@@ -18,18 +18,18 @@ jobs:
           title: "🧪 Hatch Pre-release Available for Testing"
           description: |
             **Version `${{ github.event.release.tag_name }}`** is now available for testing!
-            
+
             ⚠️ **This is a pre-release** - expect potential bugs and breaking changes
             🔬 Perfect for testing new features and providing feedback
             📋 Click [here](${{ github.event.release.html_url }}) to view what's new and download
 
             💻 Install with pip:
             ```bash
-            pip install hatch-xclam=${{ github.event.release.tag_name }}
+            pip install hatch-xclam==${{ github.event.release.tag_name }}
             ```
-            
+
             Help us make *Hatch!* better by testing and reporting [issues](https://github.com/CrackingShells/Hatch/issues)! 🐛➡️✨
           color: 0xff9500  # Orange color for pre-release
           username: "Cracking Shells Pre-release Bot"
           image: "https://raw.githubusercontent.com/CrackingShells/.github/main/resources/images/hatch_icon_dark_bg_transparent.png"
-          avatar_url: "https://raw.githubusercontent.com/CrackingShells/.github/main/resources/images/cs_core_dark_bg.png"
+          avatar_url: "https://raw.githubusercontent.com/CrackingShells/.github/main/resources/images/cs_core_dark_bg.png"

.github/workflows/release-discord-notification.yml

@@ -17,16 +17,16 @@ jobs:
           content: "<@&1418053865818951721>"
           title: "🎉 New *Hatch!* Release Available!"
           description: |
-            **Version `${{ github.event.release.tag_name }}`** has been released! 
-            
+            **Version `${{ github.event.release.tag_name }}`** has been released!
+
             🚀 Get the latest features and improvements
             📚 Click [here](${{ github.event.release.html_url }}) to view the changelog and download
 
             💻 Install with pip:
             ```bash
             pip install hatch-xclam
             ```
-            
+
             Happy MCP coding with *Hatch!* 🐣
           color: 0x00ff88
           username: "Cracking Shells Release Bot"

.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+        exclude: ^mkdocs\.yml$
+      - id: check-added-large-files
+      - id: check-toml
+
+  - repo: https://github.com/psf/black
+    rev: 23.12.1
+    hooks:
+      - id: black
+        language_version: python3.12
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.9
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+
+  - repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
+    rev: v9.11.0
+    hooks:
+      - id: commitlint
+        stages: [commit-msg]
+        additional_dependencies: ['@commitlint/cli@^18.6.1', '@commitlint/config-conventional@^18.6.2']

__reports__/standards-retrospective/02-fresh_eye_review_v0.md

@@ -0,0 +1,82 @@
+# Fresh-Eye Review — Post-Implementation Gap Analysis (v0)
+
+Date: 2026-02-19
+Follows: `01-instructions_redesign_v3.md` implementation via `__roadmap__/instructions-redesign/`
+
+## Executive Summary
+
+After the instruction files were rewritten/edited per the v3 redesign, a fresh-eye review reveals **residual stale terminology** in 6 files that were NOT in the §11 affected list, **1 stale cross-reference** in a file that WAS edited, and **1 useful addition** (the `roadmap-execution.instructions.md`) that emerged during implementation but wasn't anticipated in the architecture report. A companion JSON schema (`roadmap-document-schema.json`) is proposed and delivered alongside this report.
+
+## Findings
+
+### F1: Stale "Phase N" Terminology in Edited Files
+
+These files were in the §11 scope and were edited, but retain stale Phase references:
+
+| File | Location | Stale Text | Suggested Fix |
+|:-----|:---------|:-----------|:--------------|
+| `reporting.instructions.md` | §2 "Default artifacts" | "Phase 1: Mermaid diagrams…" / "Phase 2: Risk-driven test matrix…" | Replace with "Architecture reports:" / "Test definition reports:" (drop phase numbering) |
+| `reporting.instructions.md` | §"Specialized reporting guidance" | "Phase 1 architecture guidance" / "Phase 2 test definition reports" | "Architecture reporting guidance" / "Test definition reporting guidance" |
+| `reporting.instructions.md` | §"Where reports go" | "Use `__design__/` for durable design/roadmaps." | "Use `__design__/` for durable architectural decisions." (roadmaps go in `__roadmap__/`, already stated in reporting-structure) |
+| `reporting-architecture.instructions.md` | Title + front-matter + opening line | "Phase 1" in title, description, and body | "Stage 1" or simply "Architecture Reporting" |
+| `reporting-structure.instructions.md` | §3 README convention | "Phase 1/2/3 etc." | "Stage 1/2/3 etc." or "Analysis/Roadmap/Execution" |
+
+**Severity**: Low — cosmetic inconsistency, but agents parsing these instructions may be confused by mixed terminology.
+
+### F2: Stale "Phase N" Terminology in Files Outside §11 Scope
+
+These files were NOT listed in §11 and were not touched during the campaign:
+
+| File | Location | Stale Text | Suggested Fix |
+|:-----|:---------|:-----------|:--------------|
+| `reporting-tests.instructions.md` | Title, front-matter, §body (6+ occurrences) | "Phase 2" throughout | "Stage 1" or "Test Definition Reporting" (tests are defined during Analysis, not a separate phase) |
+| `reporting-templates.instructions.md` | Front-matter + section headers | "Phase 1" / "Phase 2" template headers | "Architecture Analysis" / "Test Definition" |
+| `reporting-templates.instructions.md` | §Roadmap Recommendation | "create `__design__/<topic>_roadmap_vN.md`" | "create a roadmap directory tree under `__roadmap__/<campaign>/`" |
+| `reporting-knowledge-transfer.instructions.md` | §"What not to do" | "link to Phase 1 artifacts" | "link to Stage 1 analysis artifacts" |
+| `analytic-behavior.instructions.md` | §"Two-Phase Work Process" | "Phase 1: Analysis and Documentation" / "Phase 2: Implementation with Context Refresh" | This is a different "phase" concept (analysis vs implementation within a single session), not the old 7-phase model. **Ambiguous but arguably fine** — the two-phase work process here is about agent behavior, not the code-change workflow. Consider renaming to "Two-Step Work Process" or "Analysis-First Work Process" to avoid confusion. |
+| `testing.instructions.md` | §2.3 | "Phase 2 report format" | "Test definition report format" |
+| `testing.instructions.md` | §2.3 reference text | "Phase 2 in code change phases" | "Stage 1 (Analysis) in code change phases" |
+
+**Severity**: Medium for `reporting-tests.instructions.md` and `reporting-templates.instructions.md` (heavily used during Stage 1 work). Low for the others.
+
+### F3: Missing Cross-Reference in `code-change-phases.instructions.md`
+
+Stage 3 (Execution) describes the breadth-first algorithm but does NOT link to `roadmap-execution.instructions.md`, which contains the detailed operational manual (failure handling escalation ladder, subagent dispatch protocol, status update discipline, completion checklist).
+
+**Suggested fix**: Add a reference in Stage 3:
+```markdown
+For the detailed operational manual (failure handling, subagent dispatch, status updates), see [roadmap-execution.instructions.md](./roadmap-execution.instructions.md).
+```
+
+### F4: `roadmap-execution.instructions.md` — Unanticipated but Valuable
+
+This file was created during the campaign but was not listed in v3 §11. It fills a genuine gap: the v3 report describes WHAT the execution model is, but the execution manual describes HOW an agent should operationally navigate it (including the escalation ladder, subagent dispatch, and status update discipline).
+
+**Recommendation**: Acknowledge in the v3 report's §11 table as an addition, or simply note it in the campaign's amendment log. No action needed — the file is well-written and consistent with the model.
+
+### F5: Schema Companion Delivered
+
+A JSON Schema (`roadmap-document-schema.json`) has been created alongside this report. It formally defines the required and optional fields for:
+- `README.md` (directory-level entry point)
+- Leaf Task files
+- Steps within leaf tasks
+- Supporting types (status values, amendment log entries, progress entries, Mermaid node definitions)
+
+Location: `cracking-shells-playbook/instructions/roadmap-document-schema.json`
+
+---
+
+## Prioritized Fix List
+
+| Priority | Finding | Files Affected | Effort |
+|:---------|:--------|:---------------|:-------|
+| 1 | F1: Stale terminology in edited files | 3 files | ~15 min (surgical text replacements) |
+| 2 | F3: Missing cross-reference | 1 file | ~2 min |
+| 3 | F2: Stale terminology in unscoped files | 5 files | ~45 min (more occurrences, some require judgment) |
+| 4 | F4: Acknowledge execution manual | 1 file (v3 report or amendment log) | ~5 min |
+
+## Decision Required
+
+- **F1 + F3**: Straightforward fixes, recommend immediate application.
+- **F2**: Larger scope. The `reporting-tests.instructions.md` and `reporting-templates.instructions.md` files have "Phase" deeply embedded. A dedicated task or amendment may be warranted.
+- **F2 (analytic-behavior)**: The "Two-Phase Work Process" is arguably a different concept. Stakeholder judgment needed on whether to rename.

docs/_config.yml

@@ -1,2 +1,2 @@
 theme: minima
-repository: CrackingShells/Hatch
+repository: CrackingShells/Hatch

docs/articles/api/cli/env.md

@@ -38,12 +38,12 @@ All handlers follow the standard signature:
 ```python
 def handle_env_command(args: Namespace) -> int:
     """Handle 'hatch env command' command.
-    
+
     Args:
         args: Namespace with:
             - env_manager: HatchEnvironmentManager instance
             - <command-specific arguments>
-    
+
     Returns:
         Exit code (0 for success, 1 for error)
     """

docs/articles/api/cli/index.md

@@ -73,13 +73,13 @@ All handlers follow a consistent signature:
 ```python
 def handle_command(args: Namespace) -> int:
     """Handle 'hatch command' command.
-    
+
     Args:
         args: Namespace with:
             - env_manager: HatchEnvironmentManager instance
             - mcp_manager: MCPHostConfigurationManager instance (if needed)
             - <command-specific arguments>
-    
+
     Returns:
         Exit code (0 for success, 1 for error)
     """

docs/articles/api/cli/mcp.md

@@ -61,13 +61,13 @@ All handlers follow the standard signature:
 ```python
 def handle_mcp_command(args: Namespace) -> int:
     """Handle 'hatch mcp command' command.
-    
+
     Args:
         args: Namespace with:
             - env_manager: HatchEnvironmentManager instance
             - mcp_manager: MCPHostConfigurationManager instance
             - <command-specific arguments>
-    
+
     Returns:
         Exit code (0 for success, 1 for error)
     """

docs/articles/api/cli/package.md

@@ -30,13 +30,13 @@ All handlers follow the standard signature:
 ```python
 def handle_package_command(args: Namespace) -> int:
     """Handle 'hatch package command' command.
-    
+
     Args:
         args: Namespace with:
             - env_manager: HatchEnvironmentManager instance
             - mcp_manager: MCPHostConfigurationManager instance
             - <command-specific arguments>
-    
+
     Returns:
         Exit code (0 for success, 1 for error)
     """

docs/articles/api/cli/system.md

@@ -37,12 +37,12 @@ All handlers follow the standard signature:
 ```python
 def handle_system_command(args: Namespace) -> int:
     """Handle 'hatch command' command.
-    
+
     Args:
         args: Namespace with:
             - env_manager: HatchEnvironmentManager instance
             - <command-specific arguments>
-    
+
     Returns:
         Exit code (0 for success, 1 for error)
     """

docs/articles/appendices/state_and_data_models.md

@@ -12,7 +12,7 @@ The complete package metadata schema is defined in `Hatch-Schemas/package/v1.2.0
 {
   "package_schema_version": "1.2.0",
   "name": "package_name",
-  "version": "1.0.0", 
+  "version": "1.0.0",
   "entry_point": "hatch_mcp_server_entry.py",
   "description": "Package description",
   "tags": ["tag1", "tag2"],