epic: git-hooks - Expand Lefthook validation and verification #217

Epic Summary

Expand and verify Lefthook validation in lightspeedwp/ThisOneTimeOnAcidCom, using the existing npm-based React/Vite implementation as the baseline.

Deliver accurate setup and rollback guidance, repeatable lifecycle tests, appropriately staged code-quality checks, and schema-aware validation for the eight approved content profiles.

Preserve the initial integration history. Do not repeat completed npm migration, branch validation or production-build wiring.

Linked Child Issues/Stories/Tasks/PRs

Planned native sub-issues:

1. docs: lefthook - Align setup and rollback guidance
2. test: lefthook - Verify installation and rollback
3. test: lefthook - Verify staging and operation safety
4. test: git-hooks - Verify production build enforcement
5. test: git-hooks - Verify journal validation
6. build: git-hooks - Add journal link validation
7. build: git-hooks - Add ESLint validation
8. build: git-hooks - Add Prettier validation
9. build: git-hooks - Add CSS validation
10. test: git-hooks - Add unit test validation
11. build: git-hooks - Add changelog validation
12. test: git-hooks - Add optional Playwright smoke validation
13. build: git-hooks - Add blog content validation
14. build: git-hooks - Add video content validation
15. build: git-hooks - Add website page validation
16. build: git-hooks - Add podcast content validation
17. build: git-hooks - Add event content validation
18. build: git-hooks - Add ebook content validation
19. build: git-hooks - Add FAQ content validation

Group foundation work first: setup documentation, installation/rollback and operation/staging safety. Verify existing build and journal checks; add independent checks only after prerequisites are ready. Journal remains covered by the existing-gate verification child.

Milestones & Timeline

No deadline, release commitment or new milestone proposed.

Sequence foundational verification first. Establish tooling and schema prerequisites before enabling dependent gates. Serialise overlapping edits to lefthook.yml and package.json, then rerun lifecycle tests.

Acceptance Criteria

• All 19 children are resolved with recorded outcomes.
• Setup, recovery, bypass and rollback documentation matches tested behaviour.
• Existing branch, journal and build checks remain functional.
• Fast validation runs before commits; heavier build/unit checks run before pushes.
• Playwright remains optional until mandatory adoption is separately agreed.
• Content hooks consume approved schemas and validator commands.
• Staging safety, filenames containing spaces and unrelated-hook preservation are demonstrated.
• Failed checks block the intended operation with actionable errors.
• Local-hook bypass limitations are explicit; CI enforcement is not assumed.
• No unrelated editorial, deployment or shared-governance changes are introduced.

Dependencies / Blockers

• Coordinate branch-validation acceptance with the existing branch-agent and regression work.
• Reuse the existing changelog validator, unit-test configuration and Playwright workstreams.
• Content-hook implementation depends on the approved schemas and schema-aware CLI.
• Lint and formatting gates require configuration and an agreed baseline.
• Hook-configuration changes share files and require coordinated integration.

Existing prerequisite issues retain their current parents and ownership. Native blocking links require an exact relationship preview before being added.

Additional Context

The supplied attachments are standard Git sample hooks. They inform stage selection but do not authorise their example policies.

Excluded:

• WordPress/Sass tooling without a repository-specific requirement.
• Arbitrary pre-build generators and automatic journal exports.
• Package-publishing lint for this private application.
• Server-side receive/checkout/update hooks, email-patch workflows and Watchman integration.
• Automatic changelog generation, version bumps and commit-message rewriting.
• Unrelated dependency upgrades or managed-workflow changes.

Repository: lightspeedwp/ThisOneTimeOnAcidCom.
Configuration: lefthook.yml.
Documentation: LEFTHOOK_SETUP.md.
Initial merged implementation: #264.
Source research: lightspeedwp/.github#3885. Reference only; no changes to that epic.

Definition of Ready

• Parent scope and child breakdown approved.
• Existing implementation and overlap reviewed.
• Tooling/schema prerequisites identified.
• Child settings and template adaptations approved.
• Estimates intentionally unset.

Definition of Done

• Child outcomes and evidence are recorded.
• Documentation matches the final implementation.
• Integration verification passes after the final hook changes.
• Applicable review and CI checks pass.
• Remaining exclusions or deferred decisions are explicit.
• Epic completion is recorded without changing unrelated issues.

Unanswered clarification questions

These questions clarify coordination and acceptance of the existing 19-child plan; they do not authorise additional hooks or mandatory Playwright adoption.

1. Which child outcomes have verified evidence, and which remain outstanding?
2. Who approves progression from foundational lifecycle and staging-safety verification to dependent validation gates?
3. What evidence confirms that setup, recovery, bypass and rollback documentation matches tested behaviour?
4. Which approved schemas and executable validator commands are prerequisites for the planned content hooks?
5. What evidence demonstrates preservation of existing checks, staging safety, filenames containing spaces and intended failure blocking?