chore: complete pending CodeRabbit improvements for agent hooks (#1126 Phase 2) #1129

Overview

This issue tracks Phase 2 of CodeRabbit improvements from #1126. These enhancements require the implementation of 4 new hooks and 1 cookbook guide created during the agent standardization initiative.

Blocking Dependencies

These improvements cannot be applied until the following files are created:

• hooks/agent-security-auditor with tests
• hooks/agent-spec-validator with tests
• hooks/multi-provider-consistency-checker with tests
• hooks/plugin-integrity-checker with tests
• cookbook/playwright-agent-creation-guide.md

See: Issue #1079 (Agent Standardization Initiative)

Pending Improvements (8 items)

Test Fixture Cleanup (3 hooks)

Add afterEach() cleanup blocks to:

• hooks/agent-security-auditor/__tests__/agent-security-auditor.test.js
• hooks/agent-spec-validator/__tests__/agent-spec-validator.test.js
• hooks/multi-provider-consistency-checker/__tests__/multi-provider-consistency-checker.test.js

Impact: Medium — Ensures test isolation and prevents state leakage

JSDoc Documentation (5 helpers)

Add JSDoc comments to helper functions:

• hooks/agent-security-auditor/__tests__/agent-security-auditor.test.js — tmpDir()
• hooks/agent-security-auditor/index.js — getAllFiles(), lineOf()
• hooks/agent-spec-validator/__tests__/agent-spec-validator.test.js — tmpAgent()
• hooks/multi-provider-consistency-checker/__tests__/multi-provider-consistency-checker.test.js — tmpAgent()
• hooks/multi-provider-consistency-checker/index.js — readProviders()

Impact: Low — Improves code maintainability and IDE support

Enhance hooks/package.json

Add npm scripts and Jest devDependency:

{
  "scripts": {
    "test": "jest",
    "lint": "eslint index.js __tests__",
    "validate": "node scripts/validate-hook-config.js"
  },
  "devDependencies": {
    "jest": "^29.0.0"
  }
}

Impact: Medium — Enables standalone hook testing and validation

Expand Test Coverage

Add test cases for edge cases:

• agent-spec-validator: Empty/non-array capabilities validation
• multi-provider-consistency-checker: Unsupported provider rejection
• plugin-integrity-checker: Invalid JSON, unsafe refs, non-string refs, missing README

Impact: High — Increases robustness and prevents regressions

Fix Cookbook Schema Link (1 file)

File: cookbook/playwright-agent-creation-guide.md (line 55-57)
Change: Update relative path to absolute

From: `schema/multi-provider-agent.schema.json`
To: `.github/schema/multi-provider-agent.schema.json`

Impact: Low — Ensures cookbook links work from any location

Document Plugin Integrity Hook (1 file)

File: hooks/plugin-integrity-checker/README.md
Add sections:

• Hook invocation instructions
• Target path inputs
• Validation result fields
• Exit-code behavior
• Error handling examples

Impact: Low — Improves discoverability and usage

Isolate Plugin Integrity Unit Tests (1 file)

File: hooks/plugin-integrity-checker/__tests__/plugin-integrity-checker.test.js
Action: Move "validates the real lightspeed-playwright-testing plugin" test to integration suite
Reason: Keep unit tests hermetic (no external file dependencies)

Impact: Medium — Ensures tests are reliable and fast

Timeline

• Phase 1: Create hooks and cookbook (Issue Epic: Multi-Provider Agent Standardization Initiative #1079)
• Phase 2 (this issue): Apply improvements to hooks
• Estimated: v1.0 release

Related Issues

• chore(code-quality): address remaining CodeRabbit feedback from PR #1108 #1126: CodeRabbit code quality improvements (tracking issue)
• PR feat(agents): Playwright Testing Agent multi-provider rewrite + Phase 1 standardization infra #1108: Original CodeRabbit review
• Epic: Multi-Provider Agent Standardization Initiative #1079: Agent standardization initiative (blocker)
• PR chore: apply CodeRabbit code quality improvements from #1126 #1127: Phase 1 improvements (merged)

Definition of Ready (DoR)

• All blocking hook files created and merged
• All blocking cookbook files created and merged
• Estimated effort and complexity assessed
• Acceptance criteria defined per improvement

Definition of Done (DoD)

• All 8 improvements applied
• All tests pass
• Linting passes
• Code reviewed and approved
• Merged to develop
• Issue chore(code-quality): address remaining CodeRabbit feedback from PR #1108 #1126 updated with completion status

Labels

code-quality, testing, documentation, coderabbit-review