aiops: claude - Implement Claude hooks and validation helpers #261

AI Ops Summary

Implement repository-appropriate Claude hooks for lightspeedwp/ThisOneTimeOnAcidCom.

Build Summary

Delivery and remaining validation — 17 October 2026

Hooks, helpers and documentation were delivered in aiops: claude - Configure agents, hooks, skills and cloud settings, merged into develop. Earlier CommonJS/ESM and nested-hook-structure findings are fixed. Hook execution, event matching, malformed input, failures, dependencies, safeguards, recursion prevention and safe logging still require validation. Acceptance checkboxes remain unchanged; author-reported tests are not independently verified.

Define justified hook events and register handlers in the appropriate settings file. Keep executable handlers and accompanying tests under scripts/claude/; document them under .claude/hooks/.

Linked Stories/Tasks/PRs/Epic

Parent: #218. Settings dependency: #259.

Milestones & Timeline

No milestone or deadline specified. Estimates remain unset.

Problem / Opportunity

Hook automation needs safe, testable behaviour without introducing destructive or unrelated shared-repository automation.

Approach / Solution

Verify supported events and repository validation commands before implementation. Keep executable code under scripts/claude/ and preserve protected files.

Acceptance Criteria

• AI workflow/agent described
• Problem/opportunity scoped
• Success metric defined
• Documentation updated
• PR uses correct branch prefix (aiops/)
• PR description updated with relevant details
• Changelog entry prepared for PR (if applicable)
• Labels/types match org standards
• Hook inventory records events, matchers, purpose, inputs, outputs and timeouts.
• Implemented handlers follow repository script-placement conventions.
• Matching, non-matching, malformed-input and failure cases are tested.
• Protected-file safeguards, recursion prevention and safe logging are verified.
• No automatic branch resets, global tooling changes or unrelated repairs are introduced.
• Debugging, disabling and rollback instructions are documented.

Additional Context

Confirm the recorded hook-schema fix against merged code. Verify handler execution from a clean checkout without manual permission changes; record invocation and failure-case evidence.

Dependencies: settings foundations, supported hook-event verification and agreed repository validation commands. Branch-prefix policy remains subject to repository verification. Do not edit CHANGELOG.md without separate authorisation.

Definition of Ready (DoR)

• AI ops goal described
• Area/action mapped
• Acceptance criteria listed
• Estimate added

Definition of Done (DoD)

• All acceptance criteria met
• Solution/automation verified
• Documentation updated
• PR uses correct branch prefix (aiops/)
• PR uses the correct PR template based on type:aiops PR label or linked issue type or linked issue type:aiops label
• Branch deleted after merge
• Linked issue(s) updated with latest status and closed after merge,
• The related epic should not be closed, instead updated with a comment to reflect the closed issue

Branch instructions

• Repository: lightspeedwp/ThisOneTimeOnAcidCom.
• Implementing target: this hook/helper issue; independently verified counterpart GitHub issue 261.
• Parent context: existing coordination relationship only. Omit its identifier/link from branch and PR association text; never use it as a native development or closing target.
• Allowed closing targets: none currently verified. Consider this issue only after its whole acceptance criteria have evidence and association effects are verified; never the coordination parent.
• Branch state: proposed new branch; historical merged configuration PR is not reusable active work.
• Branch: aiops/claude-hook-safety.
• Base: develop, checked at 4ecdb26d9655a48bf000a7c89da2f70383edce87.
• Naming policy: local guide, validator and organisation strategy. aiops fits hook/helper safety work. Proposed name checked statically only.
• PR template: verified shared AI-ops template; automatic local routing remains unresolved. Exclude sample closing and parent associations.
• Missing evidence: supported hook schema/events, input contract, timeout behaviour and clean-checkout execution. The current helper invokes dependency inspection and a build on SessionStart; neither was executed by this audit. Establish settings compatibility before changing hook wiring.
• Constraints: planning only. Separate approval required for records, branches and implementation. No force-push, merge, deployment, destructive resets or unrelated repairs. Locked settings require ownership resolution and human-only editing wherever that rule applies.

Expected file changes

Provisional plan. Existing paths read at 4ecdb26d9655a48bf000a7c89da2f70383edce87; existence is not approval or completed validation.

No speculative events or guard handlers proposed. No moves or deletions. Cloud setup, agents, skills, dependencies and protected workflows remain outside scope. Serialise shared settings/documentation changes with the settings/privacy issue, not independent simultaneous edits. Materially different findings require revised scope and approval.