forge-workflow 0.0.3 → 0.0.5

package/docs/VALIDATION.md

@@ -1,363 +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
+# 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-preflight` CLI checks prerequisites for each workflow stage.
+
+### Usage
+
+```bash
+forge-preflight <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-preflight 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-preflight status
+
+Checking project prerequisites...
+
+Validation Results:
+
+  ✓ Git repository
+  ✓ package.json exists
+  ✓ Test framework configured
+  ✓ Node.js installed
+
+✅ All checks passed!
+```
+
+---
+
+### `forge-preflight 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-preflight 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-preflight 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-preflight 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-preflight 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-preflight.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](../AGENTS.md) - Complete 7-stage workflow
+- [TDD Guide](../CLAUDE.md) - TDD principles and practices
+- [Lefthook Docs](https://github.com/evilmartians/lefthook) - Full hook configuration