xtrm-tools 2.2.0 → 2.4.0

package/project-skills/tdd-guard/docs/adr/006-phpunit-separate-repository.md

@@ -1,93 +0,0 @@
-# ADR-006: Separate Repository for PHPUnit Reporter
-
-## Status
-
-Accepted
-
-## Context
-
-We received a contribution for a PHPUnit reporter that allows PHP developers to use TDD Guard with their PHPUnit test suites. However, when attempting to publish this package to Packagist (the PHP package registry), we encountered a fundamental limitation: Packagist requires the `composer.json` file to be at the root of the repository.
-
-TDD Guard is organized as a monorepo containing:
-
-- The main CLI tool (TypeScript/npm)
-- Vitest reporter (TypeScript/npm)
-- Pytest reporter (Python/PyPI)
-- PHPUnit reporter (PHP/Packagist)
-
-This structure works well for npm (which supports workspaces) and PyPI (which can build from subdirectories), but Packagist does not support monorepos or packages in subdirectories.
-
-### Options Considered
-
-1. **Move composer.json to repository root**
-   - Would make the entire TDD Guard project appear as a PHP package
-   - Users would download all code (TypeScript, Python, etc.) just to get the PHPUnit reporter
-   - Conflicts with the project's primary identity as a CLI tool
-
-2. **Private Packagist subscription**
-   - Supports monorepos but requires paid subscription
-   - Adds ongoing cost for an open-source project
-   - Creates barrier for community adoption
-
-3. **Manual installation instructions**
-   - Users would need to configure Composer to use VCS repository
-   - Poor developer experience
-   - Reduces discoverability and adoption
-
-4. **Separate repository with automated synchronization**
-   - Maintains single source of truth in main repository
-   - Provides standard Packagist installation experience
-   - Can be automated with GitHub Actions
-
-## Decision
-
-We will create a separate repository (`tdd-guard-phpunit`) that mirrors the `reporters/phpunit` directory from the main repository. This mirror will be automatically synchronized using GitHub Actions whenever changes are pushed to the PHPUnit reporter in the main repository.
-
-### Implementation Plan
-
-1. **Initial Setup**
-   - Create `tdd-guard-phpunit` repository
-   - Use `git subtree split` to extract PHPUnit reporter history
-   - Push to new repository maintaining commit history
-   - Submit to Packagist for PHP package distribution
-
-2. **Automated Synchronization**
-   - GitHub Action triggered on pushes to `reporters/phpunit/**`
-   - Uses git subtree to maintain clean history
-   - Force pushes to mirror repository to ensure consistency
-   - Syncs relevant tags (e.g., `phpunit-v*`)
-
-3. **Clear Communication**
-   - Mirror repository README clearly states it's read-only
-   - Directs issues and PRs to main repository
-   - Explains the monorepo structure and rationale
-
-## Consequences
-
-### Positive
-
-- **Standard installation**: `composer require --dev tdd-guard/phpunit`
-- **Packagist compatibility**: Full integration with PHP ecosystem
-- **Automated updates**: No manual synchronization needed
-- **Clean history**: Git subtree preserves relevant commit history
-- **Single source of truth**: All development happens in main repository
-
-### Negative
-
-- **Additional complexity**: Must maintain synchronization workflow
-- **Delayed updates**: Packagist updates depend on GitHub Action execution
-- **Repository proliferation**: Additional repository to manage
-- **Potential confusion**: Contributors might submit PRs to wrong repository
-
-### Security Considerations
-
-- Uses GitHub Personal Access Token (PAT) with minimal required permissions
-- Token stored as repository secret, only accessible to repository admins
-- Automated workflow reduces human error in synchronization
-- Mirror repository can be made explicitly read-only if needed
-
-## Future Considerations
-
-If Packagist adds monorepo support in the future, we could deprecate the mirror repository and publish directly from the main repository. Until then, this approach provides the best balance of maintainability and user experience.
-
-The same pattern could be applied if we need to publish other language-specific packages that don't support monorepos (e.g., RubyGems, CPAN).

package/project-skills/tdd-guard/docs/adr/007-golangci-lint-path-support.md

@@ -1,83 +0,0 @@
-# ADR-007: Golangci-lint Path and Working Directory Support
-
-## Status
-
-Proposed
-
-## Context
-
-The golangci-lint integration in TDD Guard faced two specific challenges that required architectural changes to work correctly.
-
-Key problems encountered:
-
-1. **File-based linting limitations** - TDD Guard's default linter interface passes absolute file paths to be linted. When golangci-lint receives individual file paths, it cannot resolve other functions and types in the same Go package, leading to false undefined variable/function errors. golangci-lint is designed to work at the package/directory level, not individual files.
-
-2. **Working directory dependency** - golangci-lint uses the current working directory to locate the project's `go.mod` file for module resolution. This TDD Guard repository is primarily TypeScript with Go test artifacts in subdirectories (`test/artifacts/go/`). When tests run from the project root, golangci-lint fails to find the correct `go.mod` files in the test artifact directories.
-
-We considered several approaches:
-
-1. **Add module resolution to linter interface** - Make the core linter system aware of Go modules and working directories
-2. **File-based workarounds** - Continue trying to make golangci-lint work with individual files
-3. **Directory-based linting with test isolation** - Use golangci-lint's natural directory mode and isolate tests that need working directory changes
-4. **Separate Go project structure** - Move Go artifacts to a different repository
-
-## Decision
-
-We will adapt golangci-lint to work within TDD Guard's file-based linter interface using directory-based execution and test isolation, avoiding changes to the core linter architecture.
-
-Implementation details:
-
-**Directory-based linting:**
-
-- Extract unique directories from provided file paths using `dirname()`
-- Pass directories to golangci-lint instead of individual files
-- Use `--path-mode=abs` flag to support absolute path arguments
-- This allows golangci-lint to resolve Go packages correctly while maintaining the existing linter interface
-
-**Test isolation:**
-
-- Configure golangci-lint tests to run in Vitest's fork pool instead of threads pool
-- Use `process.chdir()` in tests with proper cleanup via beforeEach/afterEach hooks
-- This allows tests to change working directory to Go test artifacts without affecting other tests
-
-Key changes:
-
-```typescript
-// Directory-based argument building
-const directories = [...new Set(filePaths.map((file) => dirname(file)))]
-const args = [
-  'run',
-  '--output.json.path=stdout',
-  '--path-mode=abs',
-  ...directories,
-]
-
-// Simplified issue parsing (no path resolution needed)
-const issues = results.flatMap(toIssue)
-```
-
-**Rationale:** This approach was chosen because the situation (non-Go project testing Go linters) is rare and doesn't warrant adding brittle module resolution logic to the core linter system. The isolated test approach keeps the complexity contained to where it's needed.
-
-## Consequences
-
-### Positive
-
-- **Go language linter support** - TDD Guard now supports the most popular Go linting solution
-- **Proper package resolution** - Directory-based linting allows golangci-lint to resolve Go types and functions correctly
-- **Alignment with tooling** - Uses golangci-lint as intended (package-level analysis)
-- **Comprehensive validation** - Go developers get the same TDD enforcement as other languages
-- **Maintainable architecture** - Avoided adding Go-specific complexity to the core linter interface
-
-### Negative
-
-- **Test complexity** - Requires separate Vitest project configuration and fork pool for isolation
-- **Different execution model** - Golangci-lint behaves differently than file-based linters (ESLint)
-- **Working directory sensitivity** - Tests must manage working directory changes carefully
-
-### Neutral
-
-- **Directory-based results** - May report issues in files not explicitly requested (entire package)
-
-## Security Considerations
-
-The golangci-lint integration performs path manipulation by extracting directories from file paths using `dirname()` and passing them as command line arguments.

package/project-skills/tdd-guard/docs/adr/008-storybook-reporter-design.md

@@ -1,182 +0,0 @@
-# ADR-008: Storybook Reporter Design
-
-## Status
-
-Accepted
-
-## Context
-
-Storybook interaction tests (stories with `play` functions) provide valuable component test coverage, but TDD Guard didn't recognize these test failures as valid RED-phase evidence. This prevented developers from using TDD workflows with Storybook for component testing.
-
-We needed to design a reporter that:
-
-- Captures test results from Storybook's `@storybook/test-runner`
-- Writes results in TDD Guard's standard format
-- Handles the unique characteristics of Storybook's test model
-- Follows the established patterns from other reporters (Vitest, Jest)
-
-We considered several design decisions:
-
-1. **Test granularity** - Should we report all stories or only those with tests?
-2. **Module hierarchy** - How should we group stories into modules?
-3. **Reporter lifecycle** - Should we write on each story or accumulate results?
-4. **Render failures** - How should we handle stories that crash during render?
-5. **Data extraction** - Should we query the page or use provided context?
-
-## Decision
-
-We will implement `tdd-guard-storybook` with the following design:
-
-### Test Granularity
-
-**Only report stories with `play` functions as tests.**
-
-Stories without `play` functions are just renders and don't provide meaningful RED/GREEN signals. This aligns with how other reporters work - they don't report non-test files. TDD Guard requires actual test failures as evidence.
-
-### Module/Test Hierarchy
-
-**One module per story file, multiple stories become tests within that module.**
-
-Structure:
-
-```json
-{
-  "testModules": [
-    {
-      "moduleId": "src/Button.stories.tsx",
-      "tests": [
-        {
-          "name": "Primary",
-          "fullName": "Button > Primary",
-          "state": "passed"
-        }
-      ]
-    }
-  ]
-}
-```
-
-This matches how Vitest/Jest group tests by file. One source file = one module is intuitive and simpler to implement.
-
-### Reporter Lifecycle
-
-**Accumulate results during `postVisit`, write once on `onExit`.**
-
-API:
-
-```typescript
-async postVisit(page, context) {
-  await reporter.onStoryResult(context)
-}
-async onExit() {
-  await reporter.onComplete()
-}
-```
-
-This matches the Vitest/Jest pattern, is more efficient (one write vs N writes), provides cleaner separation of concerns, and better handles interruptions.
-
-### Render Failure Handling
-
-**Create synthetic failed test for stories that fail to render.**
-
-A story with a `play` function that crashes during render is still a failing test. This matches VitestReporter pattern for module load failures and provides visibility into all failures, not just interaction test failures.
-
-### Data Extraction Strategy
-
-**Extract minimal data from test-runner context directly, no additional page queries.**
-
-Start simple with what test-runner provides out of the box. Less complexity = fewer failure points. Can enhance later if needed.
-
-### Interruption Handling
-
-**Best-effort save on exit with "interrupted" status.**
-
-Approach:
-
-- Register process exit handler to catch interruptions
-- Write accumulated results when possible
-- Mark overall status as "interrupted"
-- Partial results better than no results
-
-This matches the Vitest/Jest pattern and TDD Guard already handles "interrupted" status.
-
-## Consequences
-
-### Positive
-
-- **Consistent patterns** - Follows established Vitest/Jest reporter patterns
-- **Efficient** - Single write operation instead of multiple
-- **Complete coverage** - Captures both interaction test failures and render failures
-- **Simple API** - Easy to configure with minimal code
-- **Robust** - Handles interruptions gracefully
-- **TDD-aligned** - Only reports actual tests, not passive renders
-
-### Negative
-
-- **Stories without `play` not tracked** - But these aren't tests, so this is intentional
-- **Accumulates in memory** - Could be an issue for extremely large test suites, but matches other reporters
-- **Storybook-specific** - Requires `@storybook/test-runner` as peer dependency
-
-### Neutral
-
-- Users need to configure `.storybook/test-runner.ts` with the reporter
-- Follows same security validations as other reporters (absolute paths, project root validation)
-- Results saved to standard location: `.claude/tdd-guard/data/test.json`
-
-## Implementation Details
-
-### Integration Test Architecture
-
-The Storybook reporter integration tests follow the same real-execution pattern as Jest, Vitest, PHPUnit, Pytest, Go, and Rust reporters.
-
-**Test Flow:**
-
-```
-Integration Test
-    ↓
-Factory (storybook.ts)
-    ↓
-Copy story files → Write configs → Spawn test-runner
-    ↓
-@storybook/test-runner (Jest + Playwright)
-    ↓
-Executes stories → Calls StorybookReporter hooks
-    ↓
-StorybookReporter.onStoryResult() → Save to FileStorage
-    ↓
-Factory reads results → Returns to test assertions
-```
-
-### Test Artifacts Structure
-
-```
-reporters/test/storybook/
-├── .storybook/
-│   └── main.js                        # Storybook configuration
-├── Calculator.js                      # Simple component module
-├── single-passing.stories.js          # Story with passing assertions
-├── single-failing.stories.js          # Story with failing expect()
-└── single-import-error.stories.js     # Story importing non-existent module
-```
-
-Stories use JavaScript (`.stories.js`) to match the repository's test file convention (`.test.js`) and reduce complexity.
-
-### Factory Implementation
-
-The `reporters/test/factories/storybook.ts` factory:
-
-1. **Copies test artifacts** - Uses existing `copyTestArtifacts` helper
-2. **Generates test-runner config** - Writes `test-runner-jest.config.js` with reporter
-3. **Starts Storybook dev server** - Spawns `storybook dev` on dynamically allocated port via `get-port`
-4. **Executes test-runner** - Spawns `test-storybook` command via `spawnSync`
-5. **Captures results** - Reporter saves to FileStorage, factory reads back
-
-### Key Design Decisions from Implementation
-
-**Test-runner integration:** Uses `@storybook/test-runner` which integrates with Jest's reporter API through `postVisit` and `onExit` hooks. The reporter accumulates results during story execution and writes once on completion.
-
-**Async server startup:** Factory implements timeout-based Storybook server detection by monitoring stdout for "Local:" or port-specific URLs. 240-second timeout accommodates slower container environments.
-
-**Optional reporter execution:** Integration tests use `Promise.allSettled` to make reporters optional, allowing tests to run even when some language-specific reporters aren't installed.
-
-**Error handling:** The reporter captures both interaction test failures and render failures (import errors, component crashes) as synthetic failed tests, ensuring complete coverage of all failure modes.

package/project-skills/tdd-guard/docs/config-migration.md

@@ -1,143 +0,0 @@
-# Configuration Migration Guide
-
-This guide helps you migrate from the legacy `MODEL_TYPE` configuration to the new `VALIDATION_CLIENT` system.
-
-## What Changed
-
-The old configuration system required:
-
-- `MODEL_TYPE` to choose between `claude_cli` or `anthropic_api`
-- `USE_SYSTEM_CLAUDE` (true/false) to choose between system or local Claude binary
-- Complex setup for finding and configuring the Claude binary
-
-The new system simplifies this with:
-
-- `VALIDATION_CLIENT` to choose between `sdk`, `api`, or `cli` (deprecated)
-- No binary configuration needed for SDK (the default)
-
-## Migration Instructions
-
-### From Claude CLI to SDK
-
-**Old configuration:**
-
-```bash
-MODEL_TYPE=claude_cli
-USE_SYSTEM_CLAUDE=true  # or false
-```
-
-**New configuration:**
-
-```bash
-VALIDATION_CLIENT=sdk  # Or omit entirely, as SDK is the default
-```
-
-The SDK client eliminates the need for:
-
-- Finding the Claude binary location
-- Setting `USE_SYSTEM_CLAUDE`
-- Dealing with symlinks or PATH configuration
-
-### From Anthropic API
-
-**Old configuration:**
-
-```bash
-MODEL_TYPE=anthropic_api
-TDD_GUARD_ANTHROPIC_API_KEY=your-api-key-here
-```
-
-**New configuration:**
-
-```bash
-VALIDATION_CLIENT=api
-TDD_GUARD_ANTHROPIC_API_KEY=your-api-key-here  # Same key variable
-```
-
-The API configuration remains similar, just with a clearer variable name.
-
-## Legacy CLI Client (Deprecated)
-
-If you must continue using the CLI client (not recommended):
-
-```bash
-VALIDATION_CLIENT=cli  # Deprecated - use sdk instead
-```
-
-You'll still need to configure the Claude binary location as described in the [CLI Binary Configuration](#cli-binary-configuration) section below.
-
-### Why CLI is Deprecated
-
-The SDK client is easier to work with and requires less configuration for different setups and operating systems.
-
-## Deprecated Variables
-
-| Variable            | Replacement         | Notes                                             |
-| ------------------- | ------------------- | ------------------------------------------------- |
-| `MODEL_TYPE`        | `VALIDATION_CLIENT` | Map `claude_cli` → `sdk`, `anthropic_api` → `api` |
-| `USE_SYSTEM_CLAUDE` | None                | No longer needed with SDK                         |
-| `TEST_MODEL_TYPE`   | None                | Use consistent configuration                      |
-
-## Common Migration Issues
-
-### API Key Conflicts
-
-For information about API key conflicts and billing, see the [Validdation Model Configuration](validation-model.md) documentation.
-
-## CLI Binary Configuration
-
-If you're still using the deprecated CLI client (`VALIDATION_CLIENT=cli`), you need to help TDD Guard find your Claude installation.
-
-### Finding Your Claude Installation
-
-```bash
-# Check system-wide installation
-which claude
-
-# Check local installation
-ls ~/.claude/local/claude
-```
-
-### Configuration Options
-
-**Option 1: Environment Variable**
-
-If Claude is in your PATH:
-
-```bash
-USE_SYSTEM_CLAUDE=true
-```
-
-**Option 2: Symlink**
-
-Point to your Claude installation:
-
-```bash
-# Create directory if needed
-mkdir -p ~/.claude/local
-
-# Create symlink to your Claude binary
-ln -s /path/to/your/claude ~/.claude/local/claude
-```
-
-Example for Homebrew on macOS:
-
-```bash
-ln -s /opt/homebrew/bin/claude ~/.claude/local/claude
-```
-
-**Option 3: Migrate Installation**
-
-Use Claude Code's built-in command:
-
-```bash
-/migrate-installer
-```
-
-## Getting Help
-
-If you encounter issues during migration:
-
-1. Check the [main configuration guide](configuration.md)
-2. Review the [Validdation Model Configuration](validation-model.md)
-3. Open an issue at [github.com/nizos/tdd-guard/issues](https://github.com/nizos/tdd-guard/issues)

package/project-skills/tdd-guard/docs/configuration.md

@@ -1,137 +0,0 @@
-# Configuration Guide
-
-This guide covers the configuration options for TDD Guard.
-
-## Environment Variables
-
-TDD Guard uses environment variables for configuration.
-Create a `.env` file in your project root:
-
-**Note:** If you're migrating from an older version using `MODEL_TYPE`, see the [Configuration Migration Guide](config-migration.md).
-
-```bash
-# Validation client for TDD enforcement (optional)
-# Options: 'sdk' (default) or 'api'
-VALIDATION_CLIENT=sdk
-
-# Model version for validation (optional)
-# Default: claude-sonnet-4-0
-# See https://docs.anthropic.com/en/docs/about-claude/models/overview
-TDD_GUARD_MODEL_VERSION=claude-sonnet-4-0
-
-# Anthropic API Key
-# Required when VALIDATION_CLIENT is set to 'api'
-# Get your API key from https://console.anthropic.com/
-TDD_GUARD_ANTHROPIC_API_KEY=your-api-key-here
-
-# Linter type for refactoring phase support (optional)
-# Options: 'eslint', 'golangci-lint' or unset (no linting)
-# See docs/linting.md for detailed setup and configuration
-LINTER_TYPE=eslint
-```
-
-## Model Configuration
-
-TDD Guard supports multiple validation clients:
-
-- **SDK** (default) - Uses your Claude Code subscription
-- **API** - Separate billing for CI/CD or faster validation
-- **CLI** (deprecated) - Legacy option, not recommended
-
-For detailed configuration, billing information, and troubleshooting, see the [Validation Model Configuration](validation-model.md) guide.
-
-If you're using the deprecated CLI client, see the [Configuration Migration Guide](config-migration.md#cli-binary-configuration).
-
-## Settings File Locations
-
-Choose where to save your settings based on your needs:
-
-- **Project settings** (`.claude/settings.json`) - Recommended for team consistency
-- **Local settings** (`.claude/settings.local.json`) - For personal preferences
-- **User settings** (`~/.claude/settings.json`) - For global configuration
-
-## Hook Configuration
-
-See the [Quick Start guide](../README.md#3-configure-claude-code-hooks) in the main README for detailed hook configuration instructions, including both interactive and manual setup methods.
-
-**Additional hooks:**
-
-- [Quick commands](quick-commands.md) - Enable `tdd-guard on/off` commands
-- [Session management](session-management.md) - Automatic data clearing and rule setup
-- [Lint integration](linting.md) - Automated refactoring support
-- [Strengthening enforcement](enforcement.md) - Prevent agents from bypassing validation
-
-## Test Reporter Configuration
-
-- **JavaScript/TypeScript**:
-  - [Vitest reporter configuration](../reporters/vitest/README.md#configuration)
-  - [Jest reporter configuration](../reporters/jest/README.md#configuration)
-- **Python**: See [Pytest reporter configuration](../reporters/pytest/README.md#configuration)
-- **PHP**: See [PHPUnit reporter configuration](../reporters/phpunit/README.md#configuration)
-- **Go**: See [Go reporter configuration](../reporters/go/README.md#configuration)
-- **Rust**: See [Rust reporter configuration](../reporters/rust/README.md#configuration)
-
-## Custom Validation Rules
-
-See [Custom Instructions](custom-instructions.md) to customize TDD validation rules to match your practices.
-
-## Data Storage
-
-TDD Guard stores context data in `.claude/tdd-guard/data/`:
-
-- `instructions.md` - Your custom TDD validation rules (created automatically, never overwritten)
-- `test.json` - Latest test results from your test runner (Vitest or pytest)
-- `todos.json` - Current todo state
-- `modifications.json` - File modification history
-- `lint.json` - ESLint results (only created when LINTER_TYPE=eslint)
-
-This directory is created automatically and should be added to `.gitignore`.
-
-## Troubleshooting
-
-### Dependency Versions
-
-#### Vitest
-
-Use the latest Vitest version to ensure correct test output format for TDD Guard:
-
-```bash
-npm install --save-dev vitest@latest
-```
-
-#### pytest
-
-For Python projects, ensure you have a recent version of pytest:
-
-```bash
-pip install pytest>=7.0.0
-```
-
-### Common Issues
-
-1. **TDD Guard not triggering**: Check that hooks are properly configured in `.claude/settings.json`
-2. **Test results not captured**: Ensure `VitestReporter` is added to your Vitest config
-3. **"Command not found" errors**: Make sure `tdd-guard` is installed globally with `npm install -g tdd-guard`
-4. **Changes not taking effect**: Restart your Claude session after modifying hooks or environment variables
-
-### Updating TDD Guard
-
-To update to the latest version:
-
-```bash
-# Update CLI tool
-npm update -g tdd-guard
-
-# For JavaScript/TypeScript projects, update the Vitest reporter in your project
-npm update tdd-guard-vitest
-
-# For Python projects, update the pytest reporter
-pip install --upgrade tdd-guard-pytest
-```
-
-Check your current version:
-
-```bash
-npm list -g tdd-guard
-pip show tdd-guard-pytest
-```

package/project-skills/tdd-guard/docs/custom-instructions.md

@@ -1,43 +0,0 @@
-# Custom TDD Instructions
-
-Customize TDD Guard's validation rules to match your specific TDD practices.
-
-## How It Works
-
-TDD Guard uses validation rules to enforce TDD principles. You can override these default rules by creating a custom instructions file at `.claude/tdd-guard/data/instructions.md`.
-
-## Automatic Setup
-
-If you have the [SessionStart hook](session-management.md) configured, the instructions file is created automatically with default rules when:
-
-- Starting a new Claude Code session
-- Resuming a session
-- Using the `/clear` command
-
-Your custom instructions are never overwritten - once created, the file remains under your control.
-
-## Creating Custom Instructions
-
-1. Edit `.claude/tdd-guard/data/instructions.md`
-2. Adjust or replace the default rules with your TDD requirements
-3. Changes take effect immediately - no restart needed
-
-## Updating to Latest Defaults
-
-When updating TDD Guard, you may want the latest default instructions:
-
-1. Delete `.claude/tdd-guard/data/instructions.md`
-2. Trigger the SessionStart hook (start new session or use `/clear`)
-3. The latest defaults will be created automatically
-
-Alternatively, you can manually copy the default rules from [`src/validation/prompts/rules.ts`](../src/validation/prompts/rules.ts).
-
-## Protecting Your Instructions
-
-Prevent agents from modifying your custom instructions by denying access to TDD Guard data. See [Strengthening TDD Enforcement](enforcement.md) for details.
-
-## Tips
-
-- Start with the default instructions and modify incrementally
-- Keep rules clear and actionable for consistent validation
-- Share effective customizations with the TDD Guard community in [GitHub Discussions](https://github.com/nizos/tdd-guard/discussions)