Hook Register

What this skill does

# hook.register Skill

Validates and registers hook manifest files, adding them to the Hook Registry for automatic enforcement.

## Purpose

While `hook.define` creates hooks on-the-fly and updates the live configuration (`.claude/hooks.yaml`), the `hook.register` skill formalizes this by validating a hook manifest and adding it to a versioned registry (`/registry/hooks.json`). This enables:

- **Version Control**: Track hooks as code with full history
- **Review Process**: Hook manifests can go through code review before activation
- **Centralized Management**: Single source of truth for all hooks in the organization
- **Formal Schema**: Ensures hooks conform to required structure

This skill is part of Betty's Layer 5 (Hooks/Policy) infrastructure, enabling automated governance and validation.

## Difference from hook.define

| Feature | hook.define | hook.register |
|---------|-------------|---------------|
| **Purpose** | Create hooks immediately | Register hook manifests for version control |
| **Output File** | `.claude/hooks.yaml` (live config) | `/registry/hooks.json` (registry) |
| **Use Case** | Quick development, testing | Production deployment, formal tracking |
| **Versioning** | Not tracked | Full version history |
| **Schema Validation** | Basic | Comprehensive |

## Usage

```bash
python skills/hook.register/hook_register.py <path_to_hook_manifest.yaml>
```

### Arguments

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| manifest_path | string | Yes | Path to the hook manifest YAML file to validate |

## Hook Manifest Schema

### Required Fields

- **name**: Unique hook identifier (kebab-case recommended, e.g., `validate-openapi-specs`)
- **version**: Semantic version (e.g., `0.1.0`)
- **description**: Human-readable description of what the hook does
- **event**: Hook trigger event (see Valid Events table below)
- **command**: Command to execute when hook triggers

### Optional Fields

- **when**: Conditional execution
  - `pattern`: File pattern to match (e.g., `"*.openapi.yaml"`, `"specs/**/*.yaml"`)
- **blocking**: Whether hook should block operation if it fails (default: `false`)
- **timeout**: Timeout in milliseconds (default: `30000`)
- **on_failure**: What to do on failure: `show_errors`, `silent`, `log_only` (default: `show_errors`)
- **status**: Hook status (`draft` or `active`, defaults to `draft`)
- **tags**: Array of tags for categorization (e.g., `["api", "validation", "compliance"]`)

### Valid Events

| Event | Triggers When | Common Use Cases |
|-------|---------------|------------------|
| `on_file_edit` | File is edited in editor | Real-time syntax validation |
| `on_file_save` | File is saved to disk | Code generation, formatting |
| `on_commit` | Git commit attempted | Breaking change detection, linting |
| `on_push` | Git push attempted | Full validation suite, security scans |
| `on_tool_use` | Any tool is used | Audit logging, usage tracking |
| `on_agent_start` | Agent begins execution | Context injection, authorization |
| `on_workflow_end` | Workflow completes | Cleanup, notifications, reporting |

## Validation Rules

The skill performs comprehensive validation:

1. **Required Fields** – Ensures `name`, `version`, `description`, `event`, and `command` are present
2. **Name Format** – Validates hook name is non-empty and follows naming conventions
3. **Version Format** – Ensures version follows semantic versioning (e.g., `0.1.0`)
4. **Event Type** – Verifies event is one of the supported triggers
5. **Command Validation** – Ensures command is non-empty
6. **Type Checking** – Validates `blocking` is boolean, `timeout` is positive number
7. **Pattern Validation** – If `when.pattern` is provided, ensures it's a valid string
8. **Name Uniqueness** – Checks that hook name doesn't conflict with existing hooks in registry

## Outputs

### Success Response

```json
{
  "ok": true,
  "status": "registered",
  "errors": [],
  "path": "hooks/validate-openapi.yaml",
  "details": {
    "valid": true,
    "status": "registered",
    "registry_updated": true,
    "manifest": {
      "name": "validate-openapi-specs",
      "version": "0.1.0",
      "description": "Validate OpenAPI specs against Zalando guidelines",
      "event": "on_file_edit",
      "command": "python skills/api.validate/api_validate.py {file_path} zalando",
      "when": {
        "pattern": "*.openapi.yaml"
      },
      "blocking": true,
      "timeout": 10000,
      "status": "active",
      "tags": ["api", "validation", "openapi"]
    }
  }
}
```

### Failure Response

```json
{
  "ok": false,
  "status": "failed",
  "errors": [
    "Invalid event: 'on_file_change'. Must be one of: on_file_edit, on_file_save, on_commit, on_push, on_tool_use, on_agent_start, on_workflow_end"
  ],
  "path": "hooks/invalid-hook.yaml",
  "details": {
    "valid": false,
    "errors": [
      "Invalid event: 'on_file_change'. Must be one of: on_file_edit, on_file_save, on_commit, on_push, on_tool_use, on_agent_start, on_workflow_end"
    ],
    "path": "hooks/invalid-hook.yaml"
  }
}
```

## Examples

### Example 1: Register OpenAPI Validation Hook

**Hook Manifest** (`hooks/validate-openapi.yaml`):

```yaml
name: validate-openapi-specs
version: 0.1.0
description: "Validate OpenAPI specs against Zalando guidelines on every edit"

event: on_file_edit
command: "python skills/api.validate/api_validate.py {file_path} zalando"

when:
  pattern: "*.openapi.yaml"

blocking: true
timeout: 10000

status: active
tags: [api, validation, openapi, zalando]
```

**Registration Command**:

```bash
$ python skills/hook.register/hook_register.py hooks/validate-openapi.yaml
{
  "ok": true,
  "status": "registered",
  "errors": [],
  "path": "hooks/validate-openapi.yaml",
  "details": {
    "valid": true,
    "status": "registered",
    "registry_updated": true
  }
}
```

### Example 2: Register Breaking Change Detection Hook

**Hook Manifest** (`hooks/prevent-breaking-changes.yaml`):

```yaml
name: prevent-breaking-changes
version: 0.1.0
description: "Block commits that introduce breaking API changes"

event: on_commit
command: "python skills/api.compatibility/check_compatibility.py {file_path} --fail_on_breaking"

when:
  pattern: "specs/**/*.yaml"

blocking: true
timeout: 30000

on_failure: show_errors

status: active
tags: [api, compatibility, breaking-changes, commit-hook]
```

### Example 3: Register Audit Log Hook

**Hook Manifest** (`hooks/audit-tool-usage.yaml`):

```yaml
name: audit-tool-usage
version: 0.1.0
description: "Log all tool usage for compliance audit trail"

event: on_tool_use
command: "python skills/audit.log/log_tool_usage.py {tool_name} {timestamp}"

blocking: false
timeout: 5000

on_failure: log_only

status: active
tags: [audit, compliance, logging]
```

## Integration

### With Workflows

Hooks can be registered as part of a workflow:

```yaml
# workflows/setup_governance.yaml
steps:
  - skill: hook.register
    args:
      - "hooks/validate-openapi.yaml"
    required: true

  - skill: hook.register
    args:
      - "hooks/prevent-breaking-changes.yaml"
    required: true
```

### With CI/CD

Validate hooks in continuous integration:

```yaml
# .github/workflows/validate-hooks.yml
name: Validate Hooks
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Validate all hooks
        run: |
          for hook in hooks/*.yaml; do
            python skills/hook.register/hook_register.py "$hook" || exit 1
          done
```

### Loading Hooks at Runtime

Once registered, hooks can be loaded from the registry:

```python
import json

with open('/registry/hooks.json') as f:
    registry = json.load(f)

active_hooks = [h for h in registry['hooks'] if h['status'] == 'active']
```

## Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| "Missing required fields: name" | Hook manifest missing required field | Add all required fields: