[Audit] Audit reusable .github assets

[ashleyshaw]

Audit Summary

Audit the reusable assets in the lightspeedwp/.github repository to determine which files are intentionally designed for cross-repository adoption and which are repo-local control-plane files that should remain specific to .github. The goal is to create a clear boundary between reusable organisational assets and repository-specific operational files, so adoption guidance, maintenance, and future automation are based on an explicit source of truth.

This audit should define:

• which .github assets are intended for reuse across client and internal repositories;
• which files are control-plane or repo-local and must not be treated as reusable templates;
• where audit outputs and reports will be stored;
• the minimum client requirements for adopting reusable assets; and
• the metrics used to assess adoption readiness, coverage, and maintenance cost.

Audit Checklist / Scope

• Scope defined and agreed
• Areas/components listed
• Audit tools or standards referenced
• Risks and findings documented
• Remediation actions mapped

In scope

• Inventory all relevant files and directories in lightspeedwp/.github
• Classify each asset as:
  • reusable/shared
  • reusable with constraints
  • repo-local control-plane
  • deprecated / not for adoption
• Identify intended consumers for each reusable asset
• Document adoption prerequisites for client repositories
• Define storage location for audit reports and supporting artefacts
• Define audit success metrics and reporting format
• Identify ownership and maintenance expectations for reusable assets

Areas/components

• GitHub Actions workflows
• Issue templates / forms
• Pull request templates
• Dependabot / repository automation config
• Documentation and guidance files
• Shared configuration or policy files
• Repo-specific governance / control-plane files

Standards / references

• Existing org instructions in AGENTS.md
• Existing org instructions in .github/custom-instructions.md
• GitHub repository health and workflow conventions
• Internal adoption and maintenance expectations

Findings / Risks

This audit is expected to surface ambiguity around what is truly reusable versus what only supports the .github repository as an organisational control plane. Without explicit classification, teams may adopt unsuitable files, duplicate repo-specific behaviour, or inherit workflows and policies that do not fit client delivery contexts.

Key risks to assess:

• accidental adoption of repo-local governance or automation files;
• unclear ownership of shared assets;
• inconsistent client implementations due to missing adoption criteria;
• maintenance overhead caused by undocumented exceptions and one-off customisation;
• weak reporting if audit outputs, metrics, and storage location are not defined up front.

Remediation Actions

• Produce a file-by-file inventory with classification and rationale
• Mark reusable assets with intended usage and constraints
• Mark repo-local control-plane files as non-adoptable
• Define canonical location for audit reports, e.g. /docs/audits/ in-repo or a dedicated tracking location agreed by the team
• Define minimum client requirements for adoption, such as supported repo type, required secrets, branch strategy, toolchain assumptions, and maintenance owner
• Define success metrics, for example:
  • number of assets reviewed
  • number and percentage classified as reusable
  • number and percentage classified as repo-local
  • number of reusable assets with documented adoption requirements
  • number of reusable assets with named owner / maintainer
  • number of unclear or disputed assets requiring follow-up
• Create follow-up issues for remediation, documentation, or extraction work where needed

Acceptance Criteria

• Audit scope and checklist completed
• Findings and risks documented
• Remediation actions assigned and tracked
• Documentation/changelog updated (if applicable)
• PR uses correct branch prefix (audit/)
• All reviewed .github assets are classified as reusable, reusable with constraints, repo-local, or deprecated
• Report storage location is agreed and documented
• Client adoption requirements are documented for reusable assets
• Audit metrics are defined and included in the final report

Additional Context

This audit should establish a practical adoption model for the .github repository, not just an inventory. The output should help answer:

• what clients or internal repos should actually copy, consume, or reference;
• what must remain local to the organisational control plane; and
• what ongoing support cost is attached to each reusable asset.

Suggested report outputs:

• inventory table with classification, owner, intended consumer, and rationale;
• adoption requirements per reusable asset;
• summary metrics dashboard;
• follow-up remediation list.

If you want, I can also turn this into a fully filled sub-issue body in your exact template format, ready to paste without any editing.

[linear-code]

LS-657