docs: repo-governance - Reconcile Spec 001 planning and traceability #409

Documentation Update Summary

Reconcile the repository-governance specification with current implementation, approved decisions and existing child-issue scopes. Produce evidence-backed planning improvements and a bounded Claude continuation prompt without duplicating implementation work.

Linked Stories/Tasks/PRs/Epic

Parent epic: #237, coordination only—not a PR development or closing target.

Specification package.

Coordinate with existing routing, migration, configuration, documentation, CI and budget workstreams. Inspect #346 for overlapping work; do not reuse, retarget or amend it automatically.

Milestones & Timeline

No dates or milestones proposed. Reconcile evidence and approval boundaries before authorising implementation.

What documentation is needed?

• Reconcile the 62-task main list and overlapping 40-entry supplementary plan; preserve task identifiers and valid delivered work.
• Incorporate the approved T018–T024 corrections and remove unsupported completion claims.
• Map all 34 requirement identifiers, existing child outcomes, tasks and verification evidence. Reconcile the earlier 33-requirement baseline without silently approving added scope.
• Correct stale constitution, runtime, integration, command, workflow and historical PR claims.
• Distinguish installed behaviour, approved targets, proposed changes and verified results.
• Draft a consistency-review report, a requirement-to-delivery evidence matrix and a Claude continuation prompt.
• Propose targeted Markdown patches to existing specification artefacts, preserving decisions, references and history.

Excluded: routing implementation, migrations, application changes, workflows, protected configuration, spending controls and unrelated record changes.

Why is this documentation important?

Conflicting plans and unsupported completion markers can misdirect implementation, duplicate existing work and prematurely close coordination issues.

Acceptance Criteria

• Documentation is clear, accurate, and up-to-date
• Includes code examples/screenshots if applicable
• Documentation is accessible and easy to find
• Changelog entry prepared for PR if user-facing update
• PR uses correct branch prefix (docs/)
• PR description updated with relevant details
• Changelog entry prepared for PR (if applicable)
• Labels/types match org standards
• Both task plans reconcile into one dependency-aware delivery map without duplicate implementation ownership.
• Approved T018–T024 corrections preserve evidenced sub-items and distinguish incomplete parent outcomes.
• Requirements, tasks, implementing children and named validation evidence are traceable; unresolved mappings remain explicit.
• Installed Gemini commands and Spec Kit behaviour are distinguished from proposed Claude workflows.
• Review report, evidence matrix and continuation-prompt Markdown drafts are complete.
• Existing architectural approvals remain intact; authority conflicts, unapproved budgets and implementation gaps remain explicit.
• PR instructions target this implementing child only; epic completion requires separate approval.

Additional Context

Reference baseline: develop at 4ecdb26d9655a48bf000a7c89da2f70383edce87; recheck before implementation.

Proposed deliverables:

• Consistency-review report
• Requirement/delivery matrix
• Claude continuation prompt

Branch instructions

• Proposed branch: docs/repo-governance-reconcile-spec-planning
• Base: current develop, rechecked before starting.
• Implementing target: this child after creation.
• No epic identifier in branch or PR association fields.
• No closing target until full child-outcome completion and association effects are verified.
• Documentation PR template applies; existing routing/label inconsistencies remain blockers to report, not permission to change automation.

The template’s unconditional changelog checklist conflicts with meta:no-changelog. Confirm applicability before implementation; do not edit protected changelog content or mark the item complete automatically.

Definition of Ready (DoR)

• Documentation need is clear and well-defined
• Related docs/issues or files linked
• Acceptance criteria listed
• Estimate added if relevant
• Milestone/release assigned (if applicable)

Definition of Done (DoD)

• Documentation meets org standards and guidelines
• Changelog entry prepared for PR (CHANGELOG.md)
• Documentation reviewed for clarity and accessibility
• Screenshots/code examples included if relevant
• PR uses correct branch prefix (docs/)
• PR uses the correct PR template based on type:docs PR label or linked issue type or linked issue type:docs label
• 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

Checklist items describe acceptance gates, not permission to close records automatically.

Unanswered clarification questions

These questions clarify planning reconciliation and traceability; they do not approve added scope or implementation.

1. Which differences between the earlier 33-requirement baseline and the recorded 34 identifiers represent approved scope?
2. Which existing implementing child owns each unresolved requirement or task, and which mappings remain uncertain?
3. What evidence is sufficient to distinguish drafted, implemented-but-unverified and verified delivery?
4. Which recorded claims require refreshed evidence from the specification package and overlapping PR automation: repo-governance - Add governance automation and validation #346?
5. What changelog applicability and review approval resolve the conflict between the template checklist and meta:no-changelog?