Define the canonical documentation and decision-record contract #2666

Problem

The accepted Base governance design and implementation plan identify package 1 as a required deliverable. This issue translates that package into a reviewed, bounded issue/PR train; it does not authorize implementation before the issue reaches Ready.

Expected behavior

Define canonical homes and owners for the PRD, area-level designs, detailed contracts, user and reference docs, README/FAQ, operations/security guidance, decisions, release notes, examples, and derived context. Add an ADR template/index and decision-capture instructions. Compare the PRD with maintainer intent; any product correction is a separate issue/PR. Include all ten D23 editorial fixes from the final review: correct good first issue/help wanted spelling; restore the named Project views; use actual GitHub close reasons; state CHANGELOG is repository-local; clarify .github/ hand-editing until a generator exists; clarify retained Rejected ADRs and typo edits; prohibit agents from posting overrides; use the merged Risk, rollback and notes heading; add Part of #N to the PR prompt; and backtick command names.

Scope and non-goals

Scope: Define canonical homes and owners for the PRD, area-level designs, detailed contracts, user and reference docs, README/FAQ, operations/security guidance, decisions, release notes, examples, and derived context. Add an ADR template/index and decision-capture instructions. Compare the PRD with maintainer intent; any product correction is a separate issue/PR. Include all ten D23 editorial fixes from the final review: correct good first issue/help wanted spelling; restore the named Project views; use actual GitHub close reasons; state CHANGELOG is repository-local; clarify .github/ hand-editing until a generator exists; clarify retained Rejected ADRs and typo edits; prohibit agents from posting overrides; use the merged Risk, rollback and notes heading; add Part of #N to the PR prompt; and backtick command names.

Non-goals: Do not silently expand scope, activate unreviewed policy, mirror issue fields onto PRs, grant agents merge/release authority, or make changes outside the named affected areas. Any new product decision or materially new work gets a separate issue and decision record.

Affected areas

• docs/governance/DESIGN.md, docs/governance/IMPLEMENTATION-PLAN.md, the canonical docs index, and the ADR template/index location selected by the design.
• Accepted source: governance design and implementation plan, PR #2664
• Parent tracker: #2665

Impact and evidence

1. Product intent: Implements only the accepted governance design and plan; any product-requirement change must be filed separately.
2. Architecture and contracts: Destination is the package-specific section of the merged governance design/implementation plan plus the affected canonical contract named above.
3. User guidance: The issue identifies likely guidance paths; the implementation PR must name updated user/FAQ/README paths or give a change-specific reason why none is affected.
4. CLI/API and reference: The affected-area list determines whether CLI/API/reference docs change; the implementation PR must cite the exact reference path or justify no impact.
5. Operations and safety: No privileged automation or merge authority is implied; the PR must list operational/security effects and any rollback.
6. Validation and testing: The issue lists the planned tests; the PR must report executed validation and explain any unavailable test.
7. Examples and downstream use: The implementation PR must identify affected examples/consumers or give evidence that this change has no downstream surface.
8. Governance and contributor process: This package changes or preserves the contributor/governance contract as described in Scope; links must point to the canonical rules.
9. Decision records: No new decision is accepted by this issue; any durable deviation requires a proposed decision record and explicit maintainer acceptance.
10. Release notes: The PR must include a user-facing release-note line or a reasoned none; this issue does not pre-decide that disposition.

These are issue-stage dispositions to refine during Triage. Before Ready, every category must have its exact destination or evidence-based no-impact reason; the PR repeats the ten-category evidence for actual changes.

Open questions

• None known. If implementation exposes an unresolved contract, return this issue to Triage and record the decision before implementation continues.

Plan

• S1: One focused PR for this issue. Use Fixes #N only if no additional slice is needed; if the maintainer approves multiple PRs, name each S1…Sn here before the first is opened and use Part of #N.
• Dependencies: None known.
• Acceptance criteria:
• The canonical document taxonomy, locations, ownership and navigation rules match the accepted governance design and current repository layout.
• The ADR lifecycle distinguishes proposed, accepted, rejected, superseded and retained records; accepted records are immutable except for corrections allowed by the design.
• The decision-capture rule and ADR index/template are discoverable from the canonical process map.
• The PRD review yields either no change with evidence or a separately tracked correction; this issue does not silently rewrite product intent.
• All ten final-review editorial nits listed in Scope are corrected and verified against the relevant design sections.
• The merged design and plan state that the proposal is accepted, and the plan points to Track implementation of the accepted Base governance plan #2665 as the implementation tracker while retaining Revise the Base ecosystem governance design and implementation plan #2663 only as the closed design-review record.
• Validation:
• Check all local Markdown links and anchors touched by the PR.
• Run documentation contract/link checks and git diff --check.
• Review the ten D23 items against the merged design and verify each has a concrete correction.
• Risks and rollback: A location choice can create duplicate sources of truth; make one canonical path and link to it. Revert the documentation PR if maintainers reject the location/ownership contract.
• Decision impact: No decision is accepted merely by implementing the issue. Record the relevant accepted decision/ADR and file a superseding record if the maintainer approves a change.