forge-workflow 0.0.1

package/docs/VALIDATION.md

@@ -0,0 +1,363 @@
+# Validation & Enforcement
+
+Forge includes built-in validation and TDD enforcement to ensure quality and consistency.
+
+## Table of Contents
+
+- [Git Hooks](#git-hooks)
+- [Validation CLI](#validation-cli)
+- [Validators by Stage](#validators-by-stage)
+- [Override Mechanisms](#override-mechanisms)
+- [Configuration](#configuration)
+
+---
+
+## Git Hooks
+
+Forge uses [Lefthook](https://github.com/evilmartians/lefthook) for fast, language-agnostic git hooks.
+
+### Pre-Commit Hook
+
+**Purpose**: Enforce TDD by blocking commits of source code without tests.
+
+**Trigger**: Before every commit
+
+**Checks**:
+- Detects staged source files (`.js`, `.ts`, `.py`, `.go`, `.java`, `.rb`, etc.)
+- Verifies corresponding test files exist (`.test.js`, `.spec.ts`, etc.)
+- Excludes config files, test files, and documentation
+
+**Behavior**:
+When source code lacks tests, offers guided recovery:
+
+```
+⚠️  Looks like you're committing source code without tests:
+
+  - src/user-service.js
+
+📋 TDD Reminder:
+  Write tests BEFORE implementation (RED-GREEN-REFACTOR)
+
+What would you like to do?
+  1. Unstage source files (keep tests staged)
+  2. Continue anyway (I have a good reason)
+  3. Abort commit (let me add tests)
+
+Your choice (1-3):
+```
+
+**Override**:
+```bash
+git commit --no-verify  # Skip in emergencies
+```
+
+### Pre-Push Hook
+
+**Purpose**: Ensure all tests pass before pushing to remote.
+
+**Trigger**: Before every push
+
+**Checks**:
+- Runs `bun test`
+- Verifies all tests pass
+
+**Override**:
+```bash
+LEFTHOOK=0 git push  # Skip all hooks
+```
+
+---
+
+## Validation CLI
+
+The `forge-validate` CLI checks prerequisites for each workflow stage.
+
+### Usage
+
+```bash
+forge-validate <command>
+```
+
+### Commands
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `status` | Check project prerequisites | Setup, onboarding |
+| `dev` | Validate before `/dev` | Before implementation |
+| `ship` | Validate before `/ship` | Before creating PR |
+
+---
+
+## Validators by Stage
+
+### `forge-validate status`
+
+**Purpose**: Check basic project setup
+
+**Checks**:
+- ✓ Git repository initialized
+- ✓ `package.json` exists
+- ✓ Test framework configured (`bun test` script)
+- ✓ Node.js installed
+
+**Example**:
+```bash
+$ forge-validate status
+
+Checking project prerequisites...
+
+Validation Results:
+
+  ✓ Git repository
+  ✓ package.json exists
+  ✓ Test framework configured
+  ✓ Node.js installed
+
+✅ All checks passed!
+```
+
+---
+
+### `forge-validate dev`
+
+**Purpose**: Validate before starting implementation (`/dev`)
+
+**Checks**:
+- ✓ On feature branch (`feat/*`, `fix/*`, `docs/*`)
+- ✓ Plan file exists (`.claude/plans/*.md`)
+- ✓ Research file exists (`docs/research/*.md`)
+- ✓ Test directory exists
+
+**Example**:
+```bash
+$ forge-validate dev
+
+Validating prerequisites for /dev stage...
+
+Validation Results:
+
+  ✓ On feature branch
+  ✓ Plan file exists
+  ✓ Research file exists
+  ✓ Test directory exists
+
+✅ All checks passed!
+```
+
+**Failed Example**:
+```bash
+$ forge-validate dev
+
+Validating prerequisites for /dev stage...
+
+Validation Results:
+
+  ✗ On feature branch
+    Not on a feature branch. Create one: git checkout -b feat/your-feature
+  ✓ Plan file exists
+  ✗ Research file exists
+    No research file found in docs/research/. Run: /research
+
+❌ Some checks failed. Please fix the issues above.
+```
+
+---
+
+### `forge-validate ship`
+
+**Purpose**: Validate before creating PR (`/ship`)
+
+**Checks**:
+- ✓ Tests exist (`.test.js`, `.spec.ts` files)
+- ✓ Tests pass (`bun test` succeeds)
+- ✓ Documentation updated (`README.md` or `docs/`)
+- ✓ No uncommitted changes
+
+**Example**:
+```bash
+$ forge-validate ship
+
+Validating prerequisites for /ship stage...
+
+Validation Results:
+
+  ✓ Tests exist
+  ✓ Tests pass
+  ✓ Documentation updated
+  ✓ No uncommitted changes
+
+✅ All checks passed!
+```
+
+---
+
+## Override Mechanisms
+
+### Git Hooks
+
+**Emergency Override** (use sparingly):
+
+```bash
+# Skip pre-commit hook
+git commit --no-verify -m "Emergency hotfix"
+
+# Skip pre-push hook
+LEFTHOOK=0 git push
+```
+
+**When to use**:
+- Emergency hotfixes
+- Work-in-progress commits (before pushing)
+- Non-code commits (docs, config)
+
+**When NOT to use**:
+- Regular development
+- Public repositories
+- Production deployments
+
+### Validation CLI
+
+The CLI provides guidance but doesn't block actions. You can proceed manually if checks fail.
+
+---
+
+## Configuration
+
+### Lefthook Configuration
+
+Edit `lefthook.yml` to customize hooks:
+
+```yaml
+pre-commit:
+  commands:
+    tdd-check:
+      run: node .forge/hooks/check-tdd.js
+      stage_fixed: false
+      tags: tdd
+      glob: "*.{js,ts,jsx,tsx,py,go,java,rb}"
+
+pre-push:
+  commands:
+    tests:
+      run: bun test
+      tags: tests
+```
+
+**Options**:
+- `run`: Command to execute
+- `stage_fixed`: Auto-stage modified files (false = safer)
+- `tags`: Categorize hooks
+- `glob`: File patterns to trigger hook
+
+### Custom Test Patterns
+
+Edit `.forge/hooks/check-tdd.js` to add custom test patterns:
+
+```javascript
+// Around line 72
+const testPatterns = [
+  `${basename}.test${ext}`,
+  `${basename}.spec${ext}`,
+  `test/${basename}.test${ext}`,
+  `tests/${basename}.test${ext}`,
+  `__tests__/${basename}.test${ext}`,
+  // Add custom patterns here
+  `${dir}/__tests__/${basename}${ext}`,
+  `spec/${basename}_spec${ext}`,  // RSpec style
+];
+```
+
+### Validation CLI Customization
+
+Edit `bin/forge-validate.js` to add custom validators:
+
+```javascript
+function validateCustomStage() {
+  console.log('Validating custom stage...\n');
+
+  check('Custom check', () => {
+    // Your validation logic
+    return true;
+  }, 'Custom error message');
+
+  return printResults();
+}
+```
+
+---
+
+## Installation
+
+Hooks are automatically installed when you run:
+
+```bash
+# Install lefthook (one-time)
+bun add -d lefthook
+
+# Set up Forge
+bunx forge setup
+```
+
+The hooks will be automatically installed in your project's `.git/hooks/` directory.
+
+**Manual installation** (if needed):
+
+```bash
+# If you prefer global installation
+bun install -g lefthook
+
+# Install hooks
+lefthook install
+```
+
+---
+
+## Troubleshooting
+
+### Hooks not running
+
+```bash
+# Check lefthook installation
+lefthook version
+
+# Reinstall hooks
+lefthook install
+
+# Check git hooks directory
+ls -la .git/hooks/
+```
+
+### False positives
+
+If the hook incorrectly flags a file:
+
+1. **Short-term**: Use `--no-verify` to skip
+2. **Long-term**: Update exclusion patterns in `.forge/hooks/check-tdd.js`
+
+### Tests failing on push
+
+```bash
+# Run tests locally
+bun test
+
+# Fix failures, then
+git push
+```
+
+---
+
+## Best Practices
+
+1. **Write tests first**: Let the hooks guide you to TDD
+2. **Don't abuse overrides**: Only use `--no-verify` in emergencies
+3. **Keep tests fast**: Pre-push hooks run on every push
+4. **Document exceptions**: If you override, explain why in commit message
+5. **Update validators**: Customize for your project's needs
+
+---
+
+## See Also
+
+- [Workflow Guide](WORKFLOW.md) - Complete 9-stage workflow
+- [TDD Guide](../CLAUDE.md) - TDD principles and practices
+- [Lefthook Docs](https://github.com/evilmartians/lefthook) - Full hook configuration