bd4207c806
Add consistent policy for what hook output to show vs suppress: - EXPOSE: errors, warnings, debug statements, uncommitted work - HIDE: format success, coverage stable, pass confirmations New files: - output-policy.sh: helper functions (expose_error, expose_warning, hide_success) - hook-output-policy.md: documentation Updated hooks to use proper Claude Code JSON output format: - check-debug.sh: expose warnings via additionalContext - post-commit-check.sh: expose uncommitted work warnings - check-coverage.sh: expose coverage drops - go-format.sh: suppress output on success - php-format.sh: suppress output on success Closes #17 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
83 lines
2.1 KiB
Markdown
83 lines
2.1 KiB
Markdown
# Hook Output Policy
|
|
|
|
Consistent policy for what hook output to expose to Claude vs hide.
|
|
|
|
## Principles
|
|
|
|
### Always Expose
|
|
|
|
| Category | Example | Reason |
|
|
|----------|---------|--------|
|
|
| Test failures | `FAIL: TestFoo` | Must be fixed |
|
|
| Build errors | `cannot find package` | Blocks progress |
|
|
| Lint errors | `undefined: foo` | Code quality |
|
|
| Security alerts | `HIGH vulnerability` | Critical |
|
|
| Type errors | `type mismatch` | Must be fixed |
|
|
| Debug statements | `dd() found` | Must be removed |
|
|
| Uncommitted work | `3 files unstaged` | Might get lost |
|
|
| Coverage drops | `84% → 79%` | Quality regression |
|
|
|
|
### Always Hide
|
|
|
|
| Category | Example | Reason |
|
|
|----------|---------|--------|
|
|
| Pass confirmations | `PASS: TestFoo` | No action needed |
|
|
| Format success | `Formatted 3 files` | No action needed |
|
|
| Coverage stable | `84% (unchanged)` | No action needed |
|
|
| Timing info | `(12.3s)` | Noise |
|
|
| Progress bars | `[=====> ]` | Noise |
|
|
|
|
### Conditional
|
|
|
|
| Category | Show When | Hide When |
|
|
|----------|-----------|-----------|
|
|
| Warnings | First occurrence | Repeated |
|
|
| Suggestions | Actionable | Informational |
|
|
| Diffs | Small (<10 lines) | Large |
|
|
| Stack traces | Unique error | Repeated |
|
|
|
|
## Implementation
|
|
|
|
Use `output-policy.sh` helper functions:
|
|
|
|
```bash
|
|
source "$SCRIPT_DIR/output-policy.sh"
|
|
|
|
# Expose failures
|
|
expose_error "Build failed" "$error_details"
|
|
expose_warning "Debug statements found" "$locations"
|
|
|
|
# Hide success
|
|
hide_success
|
|
|
|
# Pass through unchanged
|
|
pass_through "$input"
|
|
```
|
|
|
|
## Hook-Specific Policies
|
|
|
|
| Hook | Expose | Hide |
|
|
|------|--------|------|
|
|
| `check-debug.sh` | Debug statements found | Clean file |
|
|
| `post-commit-check.sh` | Uncommitted work | Clean working tree |
|
|
| `check-coverage.sh` | Coverage dropped | Coverage stable/improved |
|
|
| `go-format.sh` | (never) | Always silent |
|
|
| `php-format.sh` | (never) | Always silent |
|
|
|
|
## Aggregation
|
|
|
|
When multiple issues, aggregate intelligently:
|
|
|
|
```
|
|
Instead of:
|
|
- FAIL: TestA
|
|
- FAIL: TestB
|
|
- FAIL: TestC
|
|
- (47 more)
|
|
|
|
Show:
|
|
"50 tests failed. Top failures:
|
|
- TestA: nil pointer
|
|
- TestB: timeout
|
|
- TestC: assertion failed"
|
|
```
|