[Documentation] Implement canonical issue field values & enforce metadata consistency (#300+)

[ashleyshaw]

---

name: "📚 Documentation"
about: "Request new documentation or propose updates/clarifications to existing docs."
title: "[Documentation] Implement canonical issue field values & enforce metadata consistency (#300+)"
labels: [status:needs-triage, priority:normal, area:documentation, meta, maintenance, ci, automation]
issue_type: "Maintenance"

What documentation is needed?

Implement and enforce canonical issue field values and metadata consistency across issues and PRs from #300 upward.

• Add .github/issue-fields.yml as the canonical config for issue field values
• Add docs/ISSUE-FIELDS.md as canonical documentation
• Wire project field derivation to canonical config
• Add CI validation for issue-fields config and docs drift
• Bulk assign issue and PR assignees for historical consistency
• Backfill milestone on closed issues #300+

Why is this documentation important?

This establishes a single source of truth for issue and PR metadata, reduces drift between documented and actual field values, and improves consistency for reporting, filtering, automation, and contributor workflow. It also makes future maintenance cheaper by validating the canonical config and documentation in CI.

Acceptance Criteria

• Canonical config and docs merged
• Validation script active in workflow
• Metadata audit artefacts added
• Historical assignees backfilled for issues and PRs where required
• Milestones backfilled on closed issues #300+
• Documentation is clear, accurate, and up to date
• Documentation is accessible and easy to find

Additional Context

This work applies to issues and PR metadata from #300 onward.

Related goals:

• canonical issue field definitions
• metadata consistency across historical records
• automated validation to prevent future drift

Definition of Ready (DoR)

• Scope confirmed
• Canonical field set identified
• Related docs/issues linked
• Acceptance criteria agreed
• Milestone assigned if applicable

Definition of Done (DoD)

• .github/issue-fields.yml added and used as canonical config
• docs/ISSUE-FIELDS.md added and aligned with config
• Project field derivation reads from canonical config
• CI validates config integrity and docs drift
• Audit artefacts committed or attached
• Historical metadata backfill completed for agreed range
• PR merged to develop

[linear-code]

LS-718

[ashleyshaw]

Implementation branch and draft PR are up: #433\n\nNext: publish PR, watch checks to green, and merge into develop.

[ashleyshaw]

Targeted closeout update (2026-05-27):

The issue-fields v2 follow-up has now shipped and is merged to develop via PR #437 (merge commit cc5a8d2).

Delivered in #437:

• formalised .github/issue-fields.yml values
• strengthened docs/ISSUE-FIELDS.md
• hardened scripts/validation/validate-issue-fields.cjs
• changelog rollout note

This explicitly completes the post-#433 stabilisation for this issue-fields track.