Skip to content

docs: git-hooks - Document Lefthook setup and CodeRabbit/CI handoff #3890

Open

Description

@ashleyshaw

Documentation Update Summary

Document the verified Lefthook setup, agent feedback support, troubleshooting, rollback and CodeRabbit/CI handoff for lightspeedwp/.github.

Linked Stories/Tasks/PRs/Epic

Parent: https://linear.app/lightspeedwp/issue/GIT-2670
Uses the reviewed research, migration, agent pilot and parity evidence. No native blocker links proposed.

Milestones & Timeline

Final documentation and maintainer handoff phase after validation. No dates supplied.

What documentation is needed?

Update applicable installation and hook guidance, including docs/HUSKY_PRECOMMITS.md, with verified commands, supported platforms, lifecycle-script caveats, hook-health checks and rollback steps. Document the agent support matrix and failure-response contracts. Prepare the changelog entry and explain that CI remains final enforcement.

Record rather than silently resolve discrepancies: the live file is .coderabbit.yml and disables draft reviews; the pasted SOP-04 specifies 80% suggestion acceptance while the attached SOP-05 specifies greater than 60%. Review-policy reconciliation is separate from this documentation change.

Why is this documentation important?

Maintainers and coding agents need accurate setup and failure-feedback instructions without assuming cross-repository conventions, universal agent correction or enforcement that live rulesets have not established.

Acceptance Criteria

  • Documentation is clear, accurate, and up-to-date
  • Includes code examples/screenshots if applicable
  • Documentation is accessible and easy to find
  • Changelog entry prepared for PR if user-facing update
  • PR uses correct branch prefix (docs/)
  • PR description updated with relevant details
  • Changelog entry prepared for PR (if applicable)
  • Labels/types match org standards
  • Setup, troubleshooting and rollback match validated implementation
  • Supported and unsupported agent behaviours are explicit
  • CodeRabbit/SOP discrepancies are recorded without changing review or merge policy

Additional Context

Repository: https://github.com/lightspeedwp/.github
Baseline: 65a013b.
Relevant paths: docs/HUSKY_PRECOMMITS.md, .coderabbit.yml and scripts/check-git-hooks.mjs.
Supplied SOP: https://uploads.linear.app/0858b26b-89d0-4f9c-882a-280581c122d5/dbec476b-baa0-40d0-8022-0378ba229a3f/640b94ba-4467-436b-a754-4babe705017f?signature=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXRoIjoiLzA4NThiMjZiLTg5ZDAtNGY5Yy04ODJhLTI4MDU4MWMxMjJkNS9kYmVjNDc2Yi1iYWEwLTQwZDAtODAyMi0wMzc4YmEyMjlhM2YvNjQwYjk0YmEtNDQ2Ny00MzZiLWE3NTQtNGJhYmU3MDUwMTdmIiwiaWF0IjoxNzkxNjA5NjEzLCJleHAiOjE4MjMxODAxNzN9.3T42pl8wF3RO3jl0xGScLMxHZ7yDmVfBXvljFyQ066A
Organisation-wide rollout and locked governance edits are excluded.


Definition of Ready (DoR)

  • Documentation need is clear and well-defined
  • Related docs/issues or files linked
  • Acceptance criteria listed
  • Estimate added if relevant
  • Milestone/release assigned (if applicable)

Definition of Done (DoD)

  • Documentation meets org standards and guidelines
  • Changelog entry prepared for PR (CHANGELOG.md)
  • Documentation reviewed for clarity and accessibility
  • Screenshots/code examples included if relevant
  • PR uses correct branch prefix (docs/)
  • PR uses the correct PR template based on type:docs PR label or linked issue type or linked issue type:docs 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

Metadata

Metadata

Assignees

Type

No type

Fields

Priority

Medium

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions