ci: repo-governance - Add documentation validation workflow #239

Current delivery and branch audit — 24 October 2026

This current snapshot supersedes conflicting earlier branch instructions and implementation-status claims below. Earlier dated notes remain historical evidence, not current acceptance. No status, hierarchy, native PR association or repository change is proposed by this description patch.

• Outcome: Provide non-mutating general documentation validation.
• Recorded status: Todo. Accepted whole-child completion is not established.
• Verified implementation position: Specification-specific workflow exists; no general documentation-validation.yml found. Root .markdownlint.json and .markdownlintignore exist. Specification validation is not general documentation coverage.
• Outstanding acceptance: Approve Markdown paths/exclusions and minimum tooling; demonstrate representative valid/invalid fixtures and migration-aligned coverage.

Branch instructions

• Repository: lightspeedwp/ThisOneTimeOnAcidCom
• Implementing issue(s): this existing child; GitHub sync counterpart ci: repo-governance - Add documentation validation workflow #239 in the same repository. Linear GitHub-sync mapping retrieved; GitHub issue body/parent not independently re-read in this audit. Do not use a closing/development association until independently verified.
• Parent epic context: native parent verified; coordination only. No implementation branch/file plan belongs to the epic itself.
• Allowed closing target(s): none now. Whole-child acceptance and independent GitHub/Linear mapping/association review are required before proposing a closing target; never the parent.
• Branch state: proposed new branch
• Branch: ci/governance-documentation-validation
• Base: develop, verified at 3f583002482d80ffd1910676bcf7c63e13989b20; refresh before separately authorised implementation
• Naming policy: target instructions, contributor guide, validator, local branch guide, organisation strategy. Classification rationale: ci is the candidate code/documentation class; authorised prefix is checked independently of the Linear title. Exact proposed name passed node scripts/validate-branch-name.js --branch ci/governance-documentation-validation in this read-only audit. It is not created or approved for creation.
• Pull request template: shared pr_ci.md — explicitly read/use its sections; do not add a repository-local copy
• PR association safeguard: No parent identifier/link in a future branch name, PR title/body, coding prompt, development link or closing directive. Association/status automation settings remain unverified; do not assume “Related to” text or a hyperlink is harmless. Child references in this description are not proposed PR text.
• Constraints: preserve unrelated work; do not create/switch/rename/delete branches, force-push, merge, deploy, change settings or close records under this draft. Shared locked configuration/templates require human review. Residual protected-file declarations remain relevant despite absent guard workflow; do not equate absent automated enforcement with permission. Workflow ownership conflicts require controller/owner resolution, not local edits to managed dependency workflows.
• Conflicts or missing evidence: Fixture execution harness and intended path/exclusion rules remain to be agreed; root lint configuration changes belong to build: repo-governance - Tailor repository root configuration #258.

Expected file changes

Plan status: provisional bounded proposal, not an approved or exhaustive implementation manifest; conditional rows are not permission to act.

• Out of scope: Manuscript rewriting, automatic fixes, bot commits, foreign frontmatter schemas, protected-file guard implementation.
• Remaining discovery: Fixture execution harness and intended path/exclusion rules remain to be agreed; root lint configuration changes belong to build: repo-governance - Tailor repository root configuration #258.
• Scope-change gate: stop for revised exact scope and approval before adding materially different paths or operations. No unbounded “other files as needed”. Protected-file approval never overrides a prohibition on routine agent edits.

Evidence and handoff packet

• Recipient and request: originating issue-management audit; read-only exact existing-record preview for approval, not a new intake or implicit specialist invocation.
• Selected record: this existing child description, separate from the coordination parent; no writes performed.
• Implementing targets and criteria: this child’s existing outcome and acceptance criteria remain in force. Provide non-mutating general documentation validation. Outstanding gates: Approve Markdown paths/exclusions and minimum tooling; demonstrate representative valid/invalid fixtures and migration-aligned coverage.
• Sources checked: current Linear description/status/native parent/relations/explicit pullRequests and GitHub sync metadata; target instructions, contributor guide, validator, local branch guide, organisation strategy; the exact source paths/revisions above and current repository inventory. Shared template config checked at 47aee0722033f65d4d9d57429b410b518646b817. Some path evidence is inventory-only and is labelled as such; it is not full content/behaviour validation.
• Branch/PR evidence: Current remote inventory includes historical epic/repo-governance-lightspeedwp/ThisOneTimeOnAcidCom#237 and broad governance/testing branches; scope/base/diff fit was not verified, so none is recommended for reuse. An open application-instrumentation pull request overlaps shared configuration; refresh its head, changed paths and scope before choosing a branch or editing shared files. No reuse is approved. No native linked PR was returned for this child; descriptive/historical references are not native associations.
• Association and closing rationale: Linear GitHub-sync mapping retrieved; GitHub issue body/parent not independently re-read in this audit. Do not use a closing/development association until independently verified. No complete-child acceptance or closing target established. Linear GitHub documentation lookup identified the integration article but did not expose its detailed association content; current workspace linking/status rules remain unverified. No parent identifier/link in a future branch name, PR title/body, coding prompt, development link or closing directive. Association/status automation settings remain unverified; do not assume “Related to” text or a hyperlink is harmless. Child references in this description are not proposed PR text.
• Unresolved points and exclusions: Fixture execution harness and intended path/exclusion rules remain to be agreed; root lint configuration changes belong to build: repo-governance - Tailor repository root configuration #258. Manuscript rewriting, automatic fixes, bot commits, foreign frontmatter schemas, protected-file guard implementation.
• Approval state: draft only. Exact description-preview approval is still required; repository edits/branch actions/PRs/settings/native associations retain separate boundaries. Existing GitHub issue sync is active, so approved description changes may propagate externally; no duplicate GitHub body write is proposed.

CI Summary

Add .github/workflows/documentation-validation.yml using the approved Markdown configuration and repository-specific paths. Adapt applicable shared checks without imposing shared-only schemas or modifying manuscript content automatically.

Linked Stories/Tasks/PRs/Epic

Parent: #237. No existing child or PR relationships proposed.

Milestones & Timeline

No dates or milestones assigned. Complete the listed dependencies before implementation.

Steps / Checklist

• Task is clearly defined and actionable
• Automation/scripts referenced if applicable
• Documentation/changelog updated
• PR uses correct branch prefix (ci/)
• PR description updated with relevant details
• Changelog entry prepared for PR (if applicable)
• Labels/types match org standards

Acceptance Criteria

• Solution implemented and documented
• CI/CD passes and is stable
• No regressions in build/deploy processes
• Branch prefix is correct (ci/)
• Branch deleted/merged
• Checks are non-mutating
• Intended Markdown paths and exclusions are documented
• Representative valid and invalid fixtures demonstrate the checks
• Approved folder moves are reflected in paths

Additional Context

Target: book repository. Reference: shared workflows.

Dependencies: Markdownlint configuration; approved content/governance directory map.

The workflow filename is a proposal, not an existing file. Read target-repository instructions before implementation; template branch wording does not override those instructions.

Definition of Ready (DoR)

• Build/CI goal and scope defined
• Checklist prepared
• Estimate added

Definition of Done (DoD)

• Issue is fixed and tested
• All checklist and acceptance criteria completed
• Documentation/changelog updated if needed
• Approved by at least one maintainer
• PR uses correct branch prefix (ci/)
• 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

The template’s future epic-comment requirement does not authorise posting a comment during creation.

Source-note references and scope

Implementation reference: documentation.yml.

Adopt only applicable read-only documentation validation. Shared branding, catalogue regeneration, automated content repair and bot commits are outside this issue’s scope. Verify target paths, exclusions and invalid fixtures.

Current implementation and remaining acceptance — 19 October 2026

Reviewed against develop revision 4ecdb26d9655a48bf000a7c89da2f70383edce87. No tests, interface submissions, settings changes or metadata mutations were performed during this review. Merged changes are partial evidence, not automatic completion.

Delivered: #319 added specification-specific validation. No general documentation-validation workflow was found.

Remaining acceptance: approve Markdown configuration and paths/exclusions; implement non-mutating documentation validation with valid/invalid fixtures and migration-aligned paths.

Validation gap: specification validation does not establish general documentation CI. Locked-file guarding remains outside this issue’s scope.