epic: repo-governance - Tailor book repository tooling and governance #237

Epic Summary

Tailor repository governance, tooling and specification-driven development to the React/TypeScript/Vite application in lightspeedwp/ThisOneTimeOnAcidCom.

Use shared governance selectively. Preserve repository-specific instructions, protected content, Figma compatibility and centrally managed automation.

Current delivery position — 24 October 2026

The epic remains incomplete: 27 native children—18 In Progress, three Todo and six Backlog; none completed. The revised descriptive index adds the newly linked #453 and covers all 27; no new child or hierarchy change is proposed. No whole-child acceptance or epic closure is inferred from merged contributions.

This is a coordination record. Implementation branches, pull requests, file plans and closing targets belong to verified implementing children, never this epic. Keep contribution evidence on the owning children; do not add pull request links to this description. Existing native pull request associations are a separate relationship-cleanup proposal, not changed by this text update.

Foundational documentation and selected configuration, workflow and planning changes are present on develop at 3f583002482d80ffd1910676bcf7c63e13989b20. Their delivery and remaining acceptance belong to #238, #240, #246, #256, #257, #258 and #409. Presence and merge are partial contribution evidence, not exercised automation, completed migrations or accepted whole-child outcomes.

Verified current gaps include:

• Bash output, Gemini instructions and plan/task templates now use .github/specs/; refactor: repo-governance - Relocate Spec Kit specification output #250 still owns approved dual-location numbering, ambiguity/collision handling, compatibility and actual authored-flow verification. Preserve newer branch and path-containment safeguards rather than reintroducing delivered defaults.
• Root planning, reports, prompts and tasks remain; complete folder migrations are not demonstrated.
• Specification-validation workflow infrastructure and strict YAML workflow parsing exist. Substantive specification/catalogue checks, label configuration validation, the label-agent runner and label-contract assertions still include passing stubs; ci: repo-governance - Add workflow validation checks #240, refactor: repo-governance - Relocate Spec Kit specification output #250 and automation: repo-governance - Automate labels and PR routing #274 retain their distinct remaining outcomes.
• Budget-control contracts exist; effective accounting, exhaustion and cancellation enforcement remain unverified.
• Reconciliation drafts are delivered but still contain unsupported completion claims and stale parent/runtime/approval statements. The main checklist has 68 unique task identifiers, the supplementary phase document has 40 entries and the specification has 34 requirement identifiers. docs: repo-governance - Reconcile Spec 001 planning and traceability #409 owns reconciliation, not acceptance of other workstreams.
• Root netlify.toml now exists with Node 24/npm 10 and the former nested file is absent. build: repo-governance - Tailor repository root configuration #258 owns stale instruction reconciliation and effective installation/deployment evidence; this is not an externally verified deployment claim.
• Current-head integration and browser validation remain unestablished.
• Current package/configuration still declares and loads Tailwind tooling despite historical removal claims. build: repo-governance - Tailor repository root configuration #258 must reconcile the approved BEM direction, current Make/plugin consumers and revision-specific evidence without unapproved automatic removal.

Linked children and implementation context

The current native child relationships are preserved. The revised descriptive index below covers all 27 current children, including the newly linked #453. This update creates, reparents and closes no children; it changes no child description outside the selected 26-child update set.

Merged PRs are contribution evidence only. Epic completion requires a separate assessment of the whole approved outcome.

Current linked sub-issues — 27

Workflows

• ci: repo-governance - Add application validation workflow #238 — application build, lint and test validation.
• ci: repo-governance - Add documentation validation workflow #239 — documentation validation.
• ci: repo-governance - Add workflow validation checks #240 — workflow syntax and static validation.
• ci: repo-governance - Validate branch naming #273 — branch-name validation.
• ci: repo-governance - Validate changelog requirements #275 — changelog validation.
• automation: repo-governance - Automate labels and PR routing #274 — repository labelling and PR-routing automation.

Templates and contributor resources

• feat: repo-governance - Define book discussion templates #246 — discussion templates.
• ci: repo-governance - Verify shared issue template inheritance #247 — shared issue-template inheritance.
• ci: repo-governance - Configure shared PR template reuse #248 — PR-template reuse and selection.
• docs: repo-governance - Define saved reply reuse #249 — saved replies.
• docs: repository - Document structure and naming conventions #266 — repository structure and naming documentation.
• docs: repo-governance - Reconcile Spec 001 planning and traceability #409 — three documentation drafts are delivered; acceptance remains outstanding. Reconcile 68 unique main task identifiers, the actual 40-entry supplementary phase document and 34 requirement identifiers against all 27 native children and revision-specific evidence. Correct unsupported completion/closed-parent claims; preserve implementation ownership, task history and approval gates.
• docs: repository - Correct inherited branding and testing guidance #453 — Backlog; correct verified inherited branding and testing guidance for the book website against committed configuration. Preserve meaningful tests, legitimate author references and historical evidence. Documentation-only; runtime, test-harness, dependency and configuration changes require separate approval. Acceptance remains outstanding.

Spec Kit and content migrations

• refactor: repo-governance - Relocate Spec Kit specification output #250 — Spec Kit specification output.
• refactor: repo-governance - Organise planning documents #251 — planning documents.
• refactor: repo-governance - Organise repository reports #252 — reports.
• refactor: repo-governance - Organise repository prompts #253 — prompts.
• decision: repo-governance - Resolve script directory placement #254 — script directory placement decision.
• refactor: repo-governance - Organise repository task documents #255 — task documents.

Testing and configuration

• refactor: repo-governance - Organise test configuration and discovery #256 — test configuration and discovery.
• build: repo-governance - Tailor GitHub root configuration #257 — GitHub root configuration.
• build: repo-governance - Tailor repository root configuration #258 — repository-root configuration.

Budget controls

• automation: repo-governance - Enforce agent and skill budgets #272 — runtime agent and skill budget enforcement.

Approval reconciliation

• review: repo-governance - Reconcile locked-file approval [LOCKED-FILES-APPROVAL] #335 — reconcile exact locked-file approval, documentation-placement conditions, ownership and effective protection evidence.
• review: repo-governance - Verify consolidation approval [LABEL-UPDATE-REQUEST] #337 — verify consolidation approval and consumer-specific exceptions. Local-template requirements conflict with ci: repo-governance - Configure shared PR template reuse #248 and remain unresolved.

Legacy tooling cleanup

• chore: scripts - Clean up legacy portfolio tooling #452 — bounded review and cleanup of 46 current script files; no relocation or exporter rewrite/retirement without approval. Native parenthood is already established; no new relationship or implementation acceptance is implied.
• aiops: prompt-engineering - Tailor legacy prompts to the book website #449 — Adapt retained legacy prompts to the book website; implementation remains within prompts/, with individually approved deletions and no relocation.

Approved direction

Preserve the nine recorded governance decisions and clarification answers, including canonical specification placement, npm-only direction, Node 24, testing and styling policy.

Do not reopen approved decisions merely because repository documentation still contains pending wording. Approval of direction does not authorise unrelated protected-setting changes, automated writes or increased spending.

Milestones and sequence

Manifest and consumer inventory → configuration alignment → routing and migrations → workflow/agent integration → end-to-end verification.

No new dates or native milestones are proposed.

Acceptance criteria

• Approved manifest identifies retained, moved, added, omitted and deferred assets with owners and consumers.
• Every requirement maps to an owning child, implementation artefact and validation result.
• Approved migrations preserve content and update producers, commands, imports and links.
• Spec Kit defaults and numbering use the canonical location while preserving legacy compatibility.
• Runtime, package-manager, styling and test instructions agree with effective configuration.
• Applicable automation is exercised with approved permissions and protected-file boundaries.
• Template inheritance and routing behaviour are verified.
• Agent/workflow applicability and budget enforcement are demonstrated or explicitly deferred.
• Specification validation distinguishes substantive checks from placeholders.
• Documentation, catalogue and task states reflect verified delivery.
• Child outcomes are accepted before epic closure.

Dependencies / Blockers

• Canonical routing implementation and regression evidence remain outstanding.
• Folder-placement conflicts require reconciliation before migration.
• Historical test results are not current-head evidence.
• Effective deployment and repository-protection settings remain unverified.
• Unsupported budget enforcement must remain a visible limitation.

Definition of Ready

• Repository-specific goal and approved direction recorded.
• Child workstreams identified.
• Implementation defaults for canonical routing approved.
• Requirement/child/validation mapping reconciled.
• Outstanding technical and ownership conflicts resolved or explicitly deferred.

Definition of Done

• Approved acceptance criteria satisfied with revision-specific evidence.
• Child issues completed, or scope revised through explicit approval.
• Integration and browser results distinguish baseline failures from regressions.
• Documentation and changelog disposition accepted.
• Maintainer acceptance and explicit epic-closure decision recorded.

Retained approved scope, decisions and planning references

The following references and boundaries are retained supporting context, not new implementation or completion claims.

PKG-001 is decided: npm-only, with package-lock.json as the authoritative lockfile. #258 owns remaining package-policy reconciliation and installation/deployment validation. Verify existing Node 24 and Jest/SWC implementation rather than reintroducing it.

Target: lightspeedwp/ThisOneTimeOnAcidCom. Shared reference: lightspeedwp/.github.

Historical journal-path and governance-documentation contributions do not establish acceptance of the remaining placement decision or this epic. #254 owns the placement decision; this description patch does not transfer historical evidence into any child.

Approved scope and protection boundaries

• Preserve application/content assets, docs/, guidelines/, root contributor documentation, changelog, attribution files, archives, Figma Make compatibility and protected trackers.
• Keep executable scripts/ at root; do not introduce .github/scripts/. Preserve imports and root-relative calculations.
• Keep managed .specify/ and .gemini/ integrations; do not transplant the shared repository’s different integration wholesale.
• Keep and adapt existing .gitignore and .coderabbit.yml rather than replace them wholesale.
• Preserve both centrally managed dependency workflows. Workflow additions, permissions and protection settings require their applicable approvals.
• Root tests/ movement is not runner conversion. Document Jest, Node, Bats and Playwright discovery and results separately; colocated Jest suites belong beside the code they cover.
• Conditional moves remain plan/ → .github/plan/, reports/ → .github/reports/, repository-specific prompts/ → .github/prompts/, and tasks/ → .github/tasks/. Amend conflicting instructions and update consumers before or alongside approved migrations; preserve archives and protected master trackers.
• Folder-level issues retain their work; use one grouped issue for direct .github/ files and one for repository-root configuration. Dedicated file issues are exceptions for substantial decisions. Six workflow children retain their scopes; consolidation requires separate approval.
• Select direct .github/ files by purpose and identified consumer. A configuration entry alone does not implement Spec Kit routing. .github/tests/ is only for justified tooling support/fixtures, not an executable-test dumping ground.
• Preserve the requested root-file assessment for VERSION, jest.config.cjs, eslint.config.cjs, babel.config.cjs, .distignore, .editorconfig, .gitattributes, .gitignore, .npmrc, .nvmrc, .prettierignore, .prettierrc, .markdownlint.config.cjs, .markdownlint-cli2.cjs, .coderabbit.yml. Record add/adapt/evaluate/defer dispositions rather than blindly copying shared configuration.
• Keep text=auto first in attributes configuration. Babel needs a demonstrated consumer. Defer VERSION until version authority is resolved; omit .distignore without a packaging consumer.
• Shared locked configuration/templates require human-reviewed changes. Bounded protected-file approval is not unrestricted approval, nor evidence of effective enforcement; preserve the outstanding documentation-placement concern favouring docs/.
• Keep privileged metadata operations separate from untrusted PR-code execution. Changelog validation remains read-only without separately approved writes.
• Coordinate agent-definition/hook work with the separate Claude-agent epic; do not duplicate, reparent or expand those issues.
• Numerical budget limits, fallback, automated writes, credentials, protected settings and increased spending retain separate approval gates. Advisory budgets are not hard host-side enforcement.

References: target instructions, target package, Spec Kit creator, shared placement policy.

GitHub supports organisational community-health defaults. Local issue templates or local issue-template configuration suppress inherited issue templates; verify actual default-branch behaviour. Saved replies are personal GitHub resources, not automatically inherited resources. Discussion-form schemas/categories require validation; editorial questions, story suggestions and reader feedback remain proposed categories.

Reconciliation and cross-workstream gates

• Reconcile the historical 33-requirement baseline with the current 34 numbered identifiers and substantive coverage of all 27 currently linked children; scope additions/exclusions require explicit approval.
• Preserve source-note provenance and dispositions, including all seven Anthropic references. Direct historical pull request links are intentionally omitted from this coordination description. docs: repo-governance - Reconcile Spec 001 planning and traceability #409 owns reconciliation; preservation of every removed source link in a child has not been verified, and this patch does not perform that transfer. Matching reference counts alone is insufficient.
• Reconcile task boundaries, template selection versus routing automation, locked-file ownership, self-dependencies and unsafe parallelism without silently expanding child scope.
• Reconcile constitution precedence/ratification wording with recorded decision approvals; distinguish decision authority from implementation, settings, automated-write and spending approval.
• Assess promised models, contracts and guidance for coherence and enforcement evidence; presence alone is not acceptance.
• Map every agent and skill to applicable workflows, inputs/outputs, permissions, validation, escalation and runtime support. Record justified not-applicable cases.
• Demonstrate accounting, retries, delegation, concurrency, exhaustion, cancellation, missing-usage fallback and resumable handoff—or record explicitly approved limitations.
• Maintain migration manifests, content-preservation checks, consumer/reference updates, validation and rollback.
• Preserve accepted historical failures separately from regressions, missing dependencies, skipped checks and unrun browser QA. Collect final integrated installation/build and runner-specific evidence.
• Validate reachable styling consumers, resets, utilities, animations, themes, images, responsive/keyboard operation and Figma Make compatibility against the approved styling direction.
• Complete requirement → task → issue/PR → validation traceability. Native relationships and issue statuses are unchanged by this description rewrite.

Source-note coverage and exact reference register

This register retains source-note dispositions and non-pull-request references from the supplied pasted.md. Direct historical pull request links are intentionally removed from this coordination description; no preservation or reassociation elsewhere is claimed by this patch. Any required provenance transfer needs its own exact child-description preview and approval. The later owner-selected feature directory is .github/specs/001-repo-governance-layout-and-agentic-workflows/; the original unnumbered destination is superseded. Specification, requirements checklist, research, implementation plan and task breakdown are authored. Three reconciliation drafts are delivered for #409; reconciliation correctness, validation and owner acceptance remain outstanding. Authored or merged planning does not establish completed implementation.

Source workflow paths are reference implementations, not target filenames or instructions to copy shared governance wholesale. The target repository’s own instructions take precedence. Implementation dispositions below cover only the bounded outcomes described; additions to required checks, credentials, protected settings or automated writes retain their own approval gates.

Workflow references

Specification, agent guidance and budget references

Cross-workstream coverage gates

• Record an adopt/adapt/defer/omit rationale for every workflow reference above, including target path, task mapping and any required follow-up approval.
• Include every current agent and skill in the applicability matrix for the seven Anthropic references; distinguish shared guidance from actual runtime configuration.
• Map actionable requirements to the numbered specification, plan, tasks and existing owning issues. Do not create duplicates merely to achieve one issue per URL.
• Planning artefacts authored; reconciliation, validation and owner approval remain outstanding. Authored documentation is not evidence of completed implementation.
• Coordinate agent-definition and hook work with aiops: claude - Adapt Claude agents for repository workflows #260 and aiops: claude - Implement Claude hooks and validation helpers #261 under their separate Claude epic. Do not reparent or expand those records through this update.
• Keep required-check changes, credentials, automated writes, increased spending and locked-file edits behind their specific approval gates.

Scripts cleanup coordination

#452 owns the bounded legacy scripts cleanup. Its file-by-file plan recommends conditional exporter retirement, dependency-checked utility removal and preservation of relevant test coverage. Protected-file approval and exporter/guard decisions remain required before implementation. Directory relocation, content deletion and unrelated findings remain excluded. This plan does not establish implementation or epic completion.