[Audit] Audit maintenance ownership documentation for shared .github defaults

[ashleyshaw]

---

name: "🛡️ Audit"
about: "Propose, conduct, or document a security, accessibility, code, or process audit."
title: "[Audit] Audit maintenance ownership documentation for shared .github defaults"
labels:

• "status:needs-audit"
• "priority:normal"
• "area:documentation"
  type: "Task"
  parent_issue: "[Task] Write and validate repo adoption guide with explicit checklists for shared .github files #17"
  source_issue: "[Audit] Audit maintenance ownership documentation for shared .github defaults #330"
  status: "draft"
  created_by: "@ashleyshaw"
  created_at: "2026-05-19"
  context:
  summary: "Audit how maintenance ownership should be documented within the shared .github adoption guidance."
  relates_to:
  • "Parent issue [Task] Write and validate repo adoption guide with explicit checklists for shared .github files #17: Create repo adoption guide for shared .github defaults"
  • "Issue [Audit] Audit maintenance ownership documentation for shared .github defaults #330: Document maintenance ownership"
    focus:
  • "ownership clarity"
  • "adoption guidance"
  • "repo boundary rules"
  • "maintenance cost"

---

Audit Summary

Audit the current guidance gap around maintenance ownership in the shared .github adoption work.

This audit should determine what ownership information maintainers need when adopting shared .github defaults into other repositories, and where that ownership guidance should live so it stays clear, lightweight, and maintainable.

The work sits under the parent task to create a repeatable adoption guide for shared .github defaults. That parent issue already establishes the need to distinguish reusable assets from repo-local assets, reduce onboarding friction, and prefer the smallest workable solution. This audit should validate the maintenance-ownership part of that guidance before documentation is finalised.

Audit Checklist / Scope

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

In Scope

• Review parent issue [Task] Write and validate repo adoption guide with explicit checklists for shared .github files #17 for adoption-guide goals and constraints
• Review issue [Audit] Audit maintenance ownership documentation for shared .github defaults #330 and confirm the documentation gap around maintenance ownership
• Audit existing guidance in AGENTS.md
• Audit existing guidance in .github/custom-instructions.md
• Identify whether maintenance ownership is currently:
  • explicit
  • implied only
  • missing
  • inconsistent across files
• Determine which ownership details should be documented for adopters, including:
  • who owns shared defaults
  • who owns repo-local overrides
  • who reviews updates
  • who decides whether to adopt upstream changes
  • who maintains copied templates, workflows, or labels after adoption
• Check whether ownership guidance should live in:
  • the adoption guide
  • repo-local instructions
  • both, with different levels of detail
• Confirm whether any other child issues under parent issue [Task] Write and validate repo adoption guide with explicit checklists for shared .github files #17 affect ownership guidance
• Recommend the smallest durable documentation change

Out of Scope

• Large-scale restructuring of .github repository files
• New automation unless the audit shows clear ROI and low maintenance cost
• Rewriting unrelated adoption-guide sections not needed for ownership clarity

Findings / Risks

Working Findings

• Parent issue [Task] Write and validate repo adoption guide with explicit checklists for shared .github files #17 already requires a clear adoption guide, validation steps, and boundaries between reusable and repo-local assets.
• AGENTS.md provides global operating rules, but does not clearly define maintenance ownership for adopted .github assets in consuming repositories.
• .github/custom-instructions.md defines boundary rules and repository scope, but does not yet appear to give maintainers a simple ownership model for adopted files.
• Without explicit ownership guidance, consuming repositories may:
  • assume the control-plane repo continues to own copied files
  • fail to assign responsibility for reviewing upstream changes
  • overwrite repo-specific customisations during updates
  • leave templates or workflows stale after initial adoption

Risks

• Ownership ambiguity causes drift between the source .github repo and consuming repositories
• Maintainers cannot tell whether copied files are centrally managed or locally owned
• Adoption guidance remains incomplete even if file placement and update steps are documented
• Future automation may encode the wrong assumptions if ownership rules are not defined first

Remediation Actions

• Add a dedicated maintenance ownership section to the repo adoption guide created under parent issue [Task] Write and validate repo adoption guide with explicit checklists for shared .github files #17
• Define a simple ownership model, for example:
  • the .github control-plane repo owns the shared baseline
  • each consuming repo owns its adopted copy and local deviations
  • maintainers of the consuming repo decide when and how to adopt upstream changes
• Document which assets are intended to remain centrally governed versus locally maintained after adoption
• Add update guardrails so maintainers do not assume copied files auto-sync
• Cross-link ownership guidance to boundary rules in .github/custom-instructions.md where useful
• Raise follow-up issues only if the audit finds a separate gap that cannot be covered cleanly in the adoption guide

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/)

Additional Acceptance Criteria For This Audit

• Maintenance ownership expectations are explicitly defined for shared .github defaults
• The recommendation aligns with parent issue [Task] Write and validate repo adoption guide with explicit checklists for shared .github files #17’s documentation-first, low-maintenance approach
• The recommendation respects repo boundary rules in .github/custom-instructions.md
• The result makes clear what the source .github repo owns versus what consuming repos own after adoption
• Any follow-up work is captured as a small, separate issue rather than expanding scope here

Additional Context

Parent Issue

• #17 — Create repo adoption guide for shared .github defaults

Source Issue

• #330 — Document maintenance ownership

Relevant Guidance

• AGENTS.md sets global AI, quality, security, accessibility, and maintenance expectations
• .github/custom-instructions.md defines repo-local boundary rules for the .github control-plane repository

Suggested Audit Standard

Use a documentation-first, minimum-maintenance lens:

• prefer a clear ownership model over automation
• avoid inventing new process unless the benefit is obvious
• keep guidance explicit enough for maintainers adopting shared defaults into existing repositories
• ensure the final wording is in UK English and easy to reuse in reviewer-facing documentation

---

Definition of Ready (DoR)

• Audit scope, checklist, and goals defined
• Areas/components listed
• Dependencies and standards mapped

Definition of Done (DoD)

• Audit performed and findings documented
• Remediation actions assigned
• Documentation/changelog updated (if applicable)
• PR uses correct branch prefix (audit/)

---

[linear-code]

LS-661