Add "Change V5.2.0: Plugin Enhancements Proposal (Sprint 3 Hooks)"

Change-V5.2.0%3A-Plugin-Enhancements-Proposal-%28Sprint-3-Hooks%29.md

@@ -0,0 +1,130 @@
+> **Type:** Change Proposal Implementation
+> **Version:** V5.2.0
+> **Status:** In Progress
+> **Date:** 2026-01-27
+> **Origin:** [V5.2.0 Plugin Enhancements Proposal](Change-V5.2.0%3A-Plugin-Enhancements-Proposal)
+> **Sprint:** Sprint 3
+
+# Sprint 3: Hooks Implementation
+
+This sprint focuses on implementing 6 foundational hooks across 4 plugins. These hooks provide enforcement, validation, and detection capabilities that other features may depend on.
+
+## Sprint Goals
+
+1. Implement commit message enforcement for conventional commits
+2. Implement branch naming validation
+3. Add intelligent prompt vagueness detection
+4. Add schema change detection for data pipelines
+5. Add smart contract validation on session start
+6. Implement breaking change detection for plugin interfaces
+
+## Issues
+
+| # | Plugin | Title | Type | Priority |
+|---|--------|-------|------|----------|
+| TBD | git-flow | Commit enforcement hook | Feature | High |
+| TBD | git-flow | Branch name validation hook | Feature | High |
+| TBD | clarity-assist | Auto-suggest hook | Feature | Medium |
+| TBD | data-platform | Schema diff detection hook | Feature | Medium |
+| TBD | contract-validator | SessionStart auto-validate hook | Feature | High |
+| TBD | contract-validator | Breaking change detection | Feature | High |
+
+*Issue numbers will be updated after creation*
+
+## Technical Architecture
+
+### Hook Implementation Pattern
+
+**CRITICAL LESSON LEARNED:** All hooks must be defined in `hooks/hooks.json`, NOT inline in plugin.json.
+
+```
+plugins/{name}/
+  hooks/
+    hooks.json       <-- Hook definitions (auto-discovered)
+    *.sh             <-- Shell scripts for command-type hooks
+```
+
+### Hook Event Types for This Sprint
+
+| Hook | Event | Tool Filter | Behavior |
+|------|-------|-------------|----------|
+| Commit enforcement | `PreToolUse` | Bash (git commit) | Block if invalid format |
+| Branch validation | `PreToolUse` | Bash (git checkout -b, git switch -c) | Block if invalid name |
+| Auto-suggest | `UserPromptSubmit` | N/A | Suggest /clarity-assist |
+| Schema diff | `PostToolUse` | Edit (schema files) | Warn on breaking changes |
+| Auto-validate | `SessionStart` | N/A | Run if files changed |
+| Breaking change | `PostToolUse` | Edit (plugin interfaces) | Warn on breaks |
+
+### hooks.json Structure
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/validate-commit.sh",
+        "tool_name": "Bash"
+      }
+    ],
+    "SessionStart": [
+      {
+        "type": "command", 
+        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-check.sh"
+      }
+    ]
+  }
+}
+```
+
+## Dependencies
+
+```
+                    +------------------+
+                    | contract-validator|
+                    | SessionStart hook |
+                    +--------+---------+
+                             |
+                             v
+                    +------------------+
+                    | contract-validator|
+                    | Breaking change   |
+                    +------------------+
+
++---------------+       +----------------+
+| git-flow      |       | git-flow       |
+| Commit hook   |       | Branch hook    |
++---------------+       +----------------+
+      (independent)           (independent)
+
++---------------+       +----------------+
+| clarity-assist|       | data-platform  |
+| Auto-suggest  |       | Schema diff    |
++---------------+       +----------------+
+      (independent)           (independent)
+```
+
+The contract-validator hooks have a dependency: Breaking change detection works in conjunction with the SessionStart auto-validate hook.
+
+## Acceptance Criteria
+
+### All Hooks
+- [ ] Hook defined in `hooks/hooks.json` (NOT plugin.json)
+- [ ] Shell script tested independently
+- [ ] Hook fires on correct event
+- [ ] Non-blocking behavior where appropriate (warnings vs errors)
+- [ ] Documentation updated in plugin README
+
+### Specific Criteria
+- **Commit hook:** Validates `type(scope): description` format
+- **Branch hook:** Validates `type/description` format, lowercase, max 50 chars
+- **Auto-suggest:** Detects vague prompts, suggests but does not block
+- **Schema diff:** Detects column removals, type changes in SQL/YAML
+- **Auto-validate:** Only runs when plugin files have git changes since last check
+- **Breaking change:** Detects interface changes that break existing consumers
+
+## Lessons Applied
+
+1. **Plugin Hooks Must Be in Separate File** - All hooks in `hooks/hooks.json`
+2. **Test Assertions Match API** - Write tests alongside implementation
+3. **Each Issue Gets Feature Branch** - Follow `feat/{issue-number}-description` pattern